@ossy/tokens

@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