@ossy/tokens

Token domain package for the Ossy platform — event-sourced token entities for API keys, sign-in verification, and workspace invitations.

What this package provides

| Primitive | File | Id / export | |---|---|---| | Schema | token.schema.js | @ossy/tokens/schema/token | | Schema ids | schema-ids.js | TokenSchema | | Aggregate | token.aggregate.js | Token (kind: 'entity') | | Events | token.events.js | TokenEvents.Created, TokenEvents.Revoked | | Queries | tokens.queries.js | TokensQueries.GetTokens | | Action | get.action.js | @ossy/tokens/actions/get (GetToken) | | Task | get.task.js | @ossy/tokens/tasks/get |

@ossy/authentication, @ossy/users, and @ossy/workspaces create and revoke tokens via TokenEvents. @ossy/platform validates API tokens in UsersMiddleware.

Token schema (ADR 0006)

| Schema | Id | Purpose | |---|---|---| | Token | @ossy/tokens/schema/token | Token metadata (type, subject, description) |

Token secrets (JWT strings) live in event payloads and are redacted via Token.Redacted before returning to clients.

Getting a token

Call POST /actions with:

{
  "action": "@ossy/tokens/actions/get",
  "payload": {
    "tokenId": "token-abc"
  }
}

Returns the redacted token view (no raw JWT in the response).

Server usage

import { Token, TokenEvents, TokensQueries, TokenSchema } from '@ossy/tokens/server'

TokenSchema.token
// => '@ossy/tokens/schema/token'

const tokens = await TokensQueries.GetTokens({ subject: 'user-1' })
const view = Token.Redacted(aggregate.events, aggregate.state)

Creating tokens

Token creation is handled by feature packages that sign JWTs and emit events:

import { Aggregate } from '@ossy/event-store'
import { Token, TokenEvents } from '@ossy/tokens/server'

const event = TokenEvents.Created({
  createdBy: 'user-1',
  type: 'Api',
  subject: 'user-1',
  description: 'CLI token',
  token: signedJwt,
  expiresAt: Date.now() + 86400000,
  scopes: ['*'],
})

await Aggregate.Of(Token, event).then(Aggregate.Add(event))

The caller supplies the pre-computed token (JWT) and expiresAt — this package stays free of signing/config concerns.

Event model (ADR 0008)

| Event | Effect | |---|---| | Created | Sets id, schemaId, payload fields, scopes (default ['*']), status: 'Active' | | Revoked | Sets status: 'Revoked', revokedAt |

TokenEvents.Created emits type: '@ossy/tokens/schema/token', event: 'Created', and resourceId for the token id.

Migration

| Before | After | |---|---| | tokens/actions/get | @ossy/tokens/actions/get | | (task shared action id) | @ossy/tokens/tasks/get | | Aggregate query type: 'Token' | type: '@ossy/tokens/schema/token' | | Event aggregateId | resourceId | | Event type: 'Created' | event: 'Created' with schema type |