openvibers/openvibe.inventory

OpenVibe.Inventory

Your items, on every OpenVibe site.

Live site: https://openvibe.my/inventory · API docs: https://openvibe.services · For AI: https://openvibe.my/inventory/llms.txt
Run it: npm ci && npm run dev (Node 22 or newer) · Tests: npm test

Status: alpha (ADR-054, plan track T21 step 2). The authority, its API, pages and Live's migration script are built
and tested; Live switches to it next.
Domain: inventory.openvibe.network · Port: 5030 · Service id: inventory · Env prefix: INVENTORY
License: AGPL-3.0 (same as every OpenVibe service).

One inventory for an OpenVibe account, the way Steam's works across games. Sites, games and apps give items for what
people do; people keep them in one place and wear them on every site that shows their kind.

Purpose

OpenVibe.Inventory is the network-wide inventory for an OpenVibe account (ADR-054): one place where the items people
earn or are given across every site, game and app are held. It registers item kinds (a contract plus a renderer per
surface), the definitions an issuer publishes and the instances a person owns, and keeps what each person has equipped.
Every movement is one append-only ledger row and one inventory.* event, written in the same transaction as the change.
Nothing is sold, bought, traded or converted into OpenCoins or Vibes (ADR-054 §5).

Owns

Its own PostgreSQL database (ov_inventory) and everything in it: the tables inventory_kinds, inventory_definitions,
inventory_definition_aliases, inventory_instances, inventory_grants, inventory_equipped and inventory_ledger
(see [migrations/](migrations/)), plus the SDK's event_outbox (events not yet sent) and account_data_events (applied
export and deletion receipts). It is the authority for item kinds, definitions, instances, grant receipts, the equipped
set and the ledger. Nothing written there is ever a credential, a key or a token.

Requests are aggregated by route template, method and status class, never by raw URL; /shared, static assets, health, readiness and
/metrics are excluded. Once a minute one http.request sample per key plus the active-requests, p95 latency and event-loop-lag gauges go
to telemetry_samples (openvibe-sdk 0.46, platform.telemetry-sample@1, migration 0005_telemetry.sql); rows older than 14 days are
deleted daily. Wired in server/app.js (createHttpTelemetry, middleware) and server/index.js (flush each minute, on stop, retention).

Does not own

• Identity is OpenVibe.Network's: it issues the usr_ subjects, usernames and Network tokens, and resolves an
  @name for the Workshop. Inventory stores only the subject.
• Files are OpenVibe.Media's: a Workshop badge image is uploaded to this service's Media tenant and referenced by its
  med_ id; Inventory keeps only the id and the metadata, never the bytes.
• Event delivery is OpenVibe.Events': the outbox relay publishes Inventory's events there and the two account
  subscriptions are created there.
• OpenVibe.Live's own cosmetics tables (user_cosmetics, user_equipped) stay Live's; the migration script only
  reads them (ADR-054 §8).

Depends on

• OpenVibe.Network — sign-in (OAuth2 authorization code + PKCE, client inventory), the JWKS signing key and
  GET /internal/identity/resolve for @name: OV_NETWORK_URL, OV_NETWORK_INTERNAL_URL, OV_OAUTH_CLIENT_ID,
  OV_OAUTH_CLIENT_SECRET.
• OpenVibe.Events — the outbox relay publishes inventory.* and the account-export/deletion subscriptions are
  created there: EVENTS_URL, INVENTORY_EVENTS_SECRET, EVENTS_RELAY_INTERVAL_MS.
• OpenVibe.Media — Workshop image uploads to this service's tenant use its Network service token
  (OV_OAUTH_CLIENT_SECRET, audience openvibe.media): OV_MEDIA_INTERNAL_URL. Network grants
  [inventory, media.object.upload, openvibe.media] on namespace inventory.
• PostgreSQL (DATABASE_URL to serve, DATABASE_DIRECT_URL to migrate) and, optionally, Valkey for shared
  per-caller limit counters (VALKEY_URL).
• Packages — openvibe-contracts and openvibe-sdk (auth, db, events, account-data, limits, service, valkey),
  openvibe-shared (shell, frame, legal, seo, serve, showcase, cache-policy, metrics, ready, release), plus Express,
  helmet, ajv, busboy, pg/PGlite and iovalkey.

Capabilities

Its manifest (openvibe-contracts) registers: inventory.item.read, inventory.item.list, inventory.equip.manage,
inventory.item.grant, inventory.item.consume, inventory.definition.manage and inventory.definition.review (the
staff review route).

It calls, on other services: events.event.publish and events.subscription.manage (OpenVibe.Events; the outbox relay
and the account subscriptions) and identity.subject.resolve (OpenVibe.Network; resolving a creator's @name).

The model (ADR-054)

• Kind (live.name_effect, live.hat, …): what its items carry (a JSON Schema), where one is equipped (slots) and
  which surfaces render it (chat, overlays, the profile, game:<id>). A new kind is a contract plus a renderer, never a
  new table. Kinds are registered at boot from [server/data/kinds.json](server/data/kinds.json).
• Definition (itd_…): one item of a kind, with a name, art (a Media image, a renderer token, an emoji), an honest
  rarity (common, uncommon, rare, epic, legendary), attributes valid against the kind, its issuer and an optional
  supply cap. Rarity, attributes and the cap are fixed once it is published.
• Instance (inv_…): one definition owned by one person, with its origin (granted, earned, migrated), its state
  (owned, consumed, revoked) and, under a cap, a serial number.
• Equipped: one instance per kind and slot.
• Ledger: an append-only row for every movement, with who did it and why.

Only a kind's issuer defines and grants its items: service:live for live.*. An issuer may name grantors on
one of its items (ADR-054 §3 amendment): other services or apps that may grant that item and nothing more (no edit,
no revoke), recorded in the ledger as the actor. Live names OpenVibe.Quest on six common items, so they are earned as
quest rewards, and OpenVibe.Games on six more, earned as achievements
([server/data/live-grantors.json](server/data/live-grantors.json), applied at boot); their pages say where to earn
them. Nothing is sold, bought, traded or
converted into OpenCoins or Vibes, and there are no paid random rewards, until a later ADR covers the legal basis and
Billing (ADR-054 §5). A test fails if a route or a column for that appears.

API (/api/v1, problem+json errors)

The public reads (kinds, definitions, /people/:subject/* and /equipped) answer every origin with
Access-Control-Allow-Origin: * and no credentials, so any site can draw what people wear (openvibe-shared items.js);
every other route stays same-site.

| Route | Capability | |
|---|---|---|
| GET /kinds, /kinds/:id | inventory.item.read (public) | the kinds |
| GET /definitions?kind=&issuer=, /definitions/:id | inventory.item.read (public) | published items |
| GET /people/:subject/items, /people/:subject/equipped | inventory.item.read (public) | a person's owned items and what they wear |
| GET /people/:subject/holdings, /people/:subject/holdings/count | inventory.item.read (public) | stacked, filtered public holdings and their count |
| GET /equipped?subjects=a,b,… | inventory.item.read (public) | up to 100 equipped sets in one call (chat renders) |
| GET /me/items | inventory.item.list | the caller's own items, every state |
| GET /me/holdings, /me/holdings/count | inventory.item.list | the caller's stacked owned holdings and their count |
| PUT /me/equipped | inventory.equip.manage | equip or clear a slot |
| POST /grants | inventory.item.grant | an issuer grants an instance (idempotent per key; 409 inventory.supply_exhausted) |
| POST /instances/:id/consume, /revoke | inventory.item.consume | an issuer uses up or takes back an instance |
| POST /definitions, PATCH /definitions/:id | inventory.definition.manage | an issuer's items |

Holdings default to 60 stacks per page (maximum 200). Filters are issuer or site (a service name), kind,
rarity, equipped=true|false, tradable=true|false, and text (a substring of the name). Sort with
sort=newest|name|rarity|count. Pass next_cursor as cursor with the same filters and sort. The cursor pins the
newest instance seen on the first page, so later grants do not move stacks during paging. tradable=true currently
returns an empty set because Inventory has no trade or transfer operation. The count endpoint counts stacks after
the same filters. The original /items routes still return individual instances, including non-owned states on /me.

For example, GET /api/v1/me/holdings?kind=live.hat&limit=1 answers:

{"subject":"usr_…","holdings":[{"definition":{"id":"itd_…","kind":"live.hat","name":"Crown","rarity":"epic"},"instance":{"id":"inv_…","definition_id":"itd_…","state":"owned"},"count":3,"equipped":true,"tradable":false,"kind_slots":["hat"]}],"next_cursor":"…"}

Tokens are for audience openvibe.inventory (Network's rule: openvibe.<service>). A person acts for themself (their
token or this site's session; a cookie write must come from this site). A service
acting for a person sends X-OV-Subject: usr_… and holds the route's capability. A public read needs no token; a
token that is presented must hold inventory.item.read.

Events (openvibe-sdk outbox): inventory.item.granted, .consumed, .revoked, .equipped, .unequipped and
inventory.definition.published. Account export and deletion (ADR-033) arrive at the loopback
POST /internal/events (INVENTORY_EVENTS_SECRET; subscriptions created at boot). The export carries the person's
items, equipped set and history. The deletion removes their items and equipped set and keeps the ledger rows without
them, so supply counts stay true.

The Workshop (ADR-054 §6)

Community badges, free. A signed-in person makes one at /workshop/new: a square PNG or WebP image (64 to 512 px, at
most 200 KB, checked by its own bytes and stored in OpenVibe.Media under this service's tenant), a name and a cap of
at most 10 000. They also confirm that they made the image or may use it. It is in_review, credited to them and
shown to nobody else until staff publish it at /workshop/review (or POST /api/v1/definitions/:id/review), with a
rarity, or reject it with a reason the creator reads on /workshop/mine. A published badge is given by its creator,
by @name, as granted, within its cap and 100 gifts a day. People wear it before their name in chat and on their
profile (network.badge.image@1; the equipped read carries the image's media_id). Limits: 5 in review and 20
submissions a day per person. On account deletion a creator's badges pass to the kind's issuer, retired, without
them.

Pages

/ (what it is), /items (every item by kind), /items/:id (one item: where it shows, who gives it, how many exist),
/me (your items; Wear and Take off are plain forms), /u/:subject (a person's public inventory) and /updates.
Every page works without JavaScript. With INDEXNOW_KEY, each item page Search gains or changes is sent to search
engines (IndexNow, through openvibe-publishing/search-feed) and the key is served at /<key>.txt.

Moving Live's cosmetics (ADR-054 §8)

Live's 70 cosmetics are seeded as definitions issued by service:live, with Live's item ids kept as aliases. Then:

node --env-file=/etc/openvibe/inventory.env scripts/import-live.js --live-env /etc/openvibe/live.env           # dry run
node --env-file=/etc/openvibe/inventory.env scripts/import-live.js --live-env /etc/openvibe/live.env --apply   # convert
node --env-file=/etc/openvibe/inventory.env scripts/import-live.js --live-env /etc/openvibe/live.env --verify  # compare

The script only reads Live's database, and never prints its URL. --apply keeps unlock times and grants nothing twice.
--verify compares every person's items and slots, row for row. Live has read and written only through this API
since 2026-10-09 (INVENTORY_AUTHORITY=inventory), and its migration 0005_drop_live_cosmetics dropped Live's three
cosmetics tables on 2026-10-15.

Configuration

See [.env.example](.env.example). Required in production: OV_OAUTH_CLIENT_SECRET (the inventory OAuth client on the
Network), BASE_URL, DATABASE_URL and DATABASE_DIRECT_URL. The database is the only required readiness check; the
Network signing key, the OAuth client and Valkey are optional (the service says so, per check, on /api/ready).

Development

npm install
fnm exec --using=22 npm test        # every test/*.test.js, on temp PGlite databases with a mock Network
fnm exec --using=22 npm run dev     # http://localhost:5030

Without DATABASE_URL development uses an embedded PGlite database in data/pglite (one process only). npm run test:pg runs the same suite through PostgreSQL and PgBouncer (see [.github/workflows/ci.yml](.github/workflows/ci.yml)).

Acceptance

npm test runs every [test/*.test.js](test/) in its own process ([test/run.js](test/run.js)) against temp PGlite
databases and an in-process mock Network, so no test needs the network or a running site. npm run test:pg runs the same
suite through PostgreSQL and PgBouncer. The main files:

• [test/inventory-api.test.js](test/inventory-api.test.js) — boot seeds Live's five kinds, the Workshop badge and 70
  definitions; a grant is namespaced, idempotent and capped (serials); attributes are validated against the kind;
  equipping is one item per slot; public reads show owned items and the owner's own read every state; consume/revoke;
  a presented token must hold inventory.item.read; no buy/sell/trade route or money column exists.
• [test/workshop.test.js](test/workshop.test.js) — a badge is judged by its own bytes (square PNG/WebP, 64–512 px, at
  most 200 KB), submitted in review, published or rejected by staff with a reason, given by @name, limited (5 in
  review, 20 submissions and 100 gifts a day), and taken down with or without revoking every copy.
• [test/grantors.test.js](test/grantors.test.js) — Live names Quest on its six reward items; a grantor grants that item
  only (no edit, no revoke), and Live sets and clears the list.
• [test/account-data.test.js](test/account-data.test.js) — account export and deletion over the signed loopback route:
  the ledger rows stay without their subject, supply counts stay true, and a creator's badges pass to the kind, retired.
• [test/import-live.test.js](test/import-live.test.js) — Live's cosmetics move row for row: the dry run, --apply (origin
  migrated, unlock time kept, idempotent) and --verify.
• [test/public-cors.test.js](test/public-cors.test.js) — the public reads answer every origin with * and no credentials;
  every other route stays same-site. [test/caller-limits.test.js](test/caller-limits.test.js) — a caller past its limit
  gets 429 problem+json with Retry-After, the declared budgets hold, and health/ready/metrics are never limited.
• [test/auth-ops.test.js](test/auth-ops.test.js), [test/auth-jwks.test.js](test/auth-jwks.test.js) and
  [test/security-session.test.js](test/security-session.test.js) — PKCE sign-in and truthful readiness; the Network JWKS
  fetch, rotation and outage; only a real Network person token is a session.
• [test/security-secrets.test.js](test/security-secrets.test.js), [test/no-internal-key.test.js](test/no-internal-key.test.js)
  and [test/open-redirect.test.js](test/open-redirect.test.js) — the OAuth client secret never leaves in a response, the
  database or a log; no X-Internal-Key path; next= never leaves the site.
• [test/discovery.test.js](test/discovery.test.js), [test/layout.test.js](test/layout.test.js) and
  [test/asset-cache.test.js](test/asset-cache.test.js) — robots/sitemap/llms and JSON-LD, the server-rendered shell and
  the boost marker, and the asset cache headers.
• [test/nginx-auth-limit.test.js](test/nginx-auth-limit.test.js), [test/service-kit.test.js](test/service-kit.test.js) and
  [test/perf-budget.test.js](test/perf-budget.test.js) — the nginx /auth/me zone, the graceful stop order, and the home
  page's size budgets.

Deploy (for the lead)

• Deploy: sudo ovhost deploy inventory on the host (git checkout at /opt/inventory.openvibe.network, unit
  openvibe-inventory.service on 127.0.0.1:5030, env /etc/openvibe/inventory.env, database ov_inventory on the data role).
• nginx: [deploy/nginx/inventory.openvibe.network.conf](deploy/nginx/inventory.openvibe.network.conf), installed with ov-vhost-install.
• Rollback: ovhost puts the previous sha back by itself when /api/ready does not answer after the restart.
• Network: OAuth client inventory; grants events.event.publish and events.subscription.manage (openvibe.events),
  then the account grants; the issuers' grants (live: inventory.item.grant, inventory.item.consume,
  inventory.definition.manage, inventory.item.list, inventory.equip.manage, inventory.item.read).
• The vhost uses the openvibe.network wildcard certificate.

Security (threat notes)

Reporting a vulnerability: [SECURITY.md](SECURITY.md).

• Session tokens are httpOnly cookies; a FedCM assertion or an app or service token is never a session.
• Secrets live only in the env file; only environment variable names appear in code and docs, and no secret is logged.
• Request bodies are never logged.
• Nothing in a request may decide a URL this service fetches: a caller's URL goes to OpenVibe.Tools, whose own guard
  decides what may be fetched.

---

Part of the OpenVibe network. Built in the open by OpenVibers.

<!-- versions:start -->

• openvibe-contracts: v0.419.0
• openvibe-sdk: v0.161.0
• openvibe-shared: v4.235.0
• openvibe-publishing: v1.7.0

<!-- versions:end -->

Account hub deployment (review before merging)

PUBLIC_URL=https://openvibe.my/inventory overrides BASE_URL for browser URLs and
SSO's default callback. Without it, the existing unprefixed deployment is unchanged.
Inventory uses /inventory, /inventory/all, /inventory/<itd_id>, /inventory/workshop,
/inventory/u/<subject> and /inventory/updates. APIs and feeds on the original host stay available.
INVENTORY_REDIRECT_LEGACY=true enables permanent redirects for the old page routes only,
preserving query strings. Leave it unset until the new deployment is verified.

server/auth/scoped-session.js adapts the SDK's Express boundary. Inventory's own
session, flow and hint cookies use inventory_ov_*, host-only at /inventory.
Mounted requests prefer the hub's root ov_token, verified by the same SDK verifier
against Inventory's configured issuer and audience (openvibe.network by default).
No audience is added or bypassed. Hub refresh and OAuth flow cookies are never borrowed
or written, and a previous Inventory refresh token cannot replace the hub viewer.
Guests render without an automatic OAuth redirect. Explicit Inventory OAuth still uses
SDK PKCE, state verification and error recovery. The original host is unchanged.

After review, deploy in this order:

1. Merge/deploy the companion Network PR with
   /home/workstation/openvibe/work/tools/merge-deploy.sh 'OpenVibe.Network#<N>:network' < /dev/null.
   Its boot seed merges the new callback into existing clients, keeping old callbacks.
   Install Network's deploy/nginx/parked-domains.conf with sudo ov-vhost-install
   using the host's installed filename. The /inventory proxy preserves the prefix.
2. Back up /etc/openvibe/inventory.env with sudo before editing it (never print its contents).
   Set PUBLIC_URL=https://openvibe.my/inventory; if OV_OAUTH_REDIRECT_URI is set,
   set it to https://openvibe.my/inventory/auth/callback. Leave legacy redirects disabled.
   Deploy with /home/workstation/openvibe/work/tools/merge-deploy.sh 'OpenVibe.Inventory#<N>:inventory' < /dev/null.
3. Verify hub and Inventory sign-in together, silent entry from Network, refresh, sign-out,
   Workshop forms, assets and API callers. Use networkToken() from tools/site-signin.js
   with the probe password loaded inline on the host, then follow the /inventory silent
   flow in a browser with a path-aware cookie jar. That helper's signIn() assumes root
   /auth and cannot test this prefix or hub cookie coexistence. Never print credentials
   or cookies. The live check is pending
   until the reviewed callback and prefix are deployed. Then enable
   INVENTORY_REDIRECT_LEGACY=true and redeploy Inventory to activate the 301 table.

Local coverage: npm test -- base-path auth-ops security-session workshop discovery search-index.