@comity/auth-tokens 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Filippo Bovo and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,60 @@
+# @comity/auth-tokens
+
+Token envelope and facade primitives for Comity.
+
+---
+
+## Purpose
+
+Defines token-facing contracts used to structure and issue authentication tokens. Provides a default facade that transports and authentication adapters consume without coupling to a specific token implementation.
+
+---
+
+## Scope
+
+This package:
+
+- ✅ defines token envelope contracts for issued tokens
+- ✅ provides a token facade contract and a default implementation
+- ✅ exposes typed input structure for token issuance
+
+This package does NOT:
+
+- ❌ verify or sign tokens
+- ❌ manage authentication sessions or assurance
+- ❌ implement transport-level concerns
+
+---
+
+## Public API
+
+- `AuthTokenEnvelope` — structured wrapper for issued token pairs
+- `AuthTokenFacade` — domain-level contract for token operations
+- `IssueTokensInput` — typed input for token issuance
+- `DefaultAuthTokenFacade` — default encapsulation of token issuance
+
+No exhaustive reference; see docs for constraints.
+
+---
+
+## Documentation
+
+- docs/overview.md
+- docs/conventions.md
+
+---
+
+## Related Packages
+
+- @comity/auth — authentication domain contracts
+- @comity/auth-jose — JOSE token adapter
+
+---
+
+## Status
+
+Stable
+
+_Review Completed: 2026-07-25_
+_Reviewer: Hobiri MAGI (DeepSeek v4 Pro)_
+_Compliance Score: 99.5% (Green)_

package/dist/cjs/contracts/envelope.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=envelope.js.map

package/dist/cjs/contracts/facade.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=facade.js.map

package/dist/cjs/facade/default.js

@@ -0,0 +1,118 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DefaultAuthTokenFacade = void 0;
+const errors_1 = require("@comity/auth/errors");
+/**
+ * Default implementation of the AuthTokenFacade.
+ */
+class DefaultAuthTokenFacade {
+    /**  */
+    #auth;
+    /**  */
+    #tokens;
+    /**
+     * @param auth - The authentication facade to use for session management
+     * @param tokens - The token service to use for token operations
+     */
+    constructor(auth, tokens) {
+        this.#auth = auth;
+        this.#tokens = tokens;
+    }
+    /**
+     * @inheritdoc
+     */
+    async authenticate(token, now) {
+        const result = await this.#tokens.verifyAccessToken(token);
+        if (!result.ok) {
+            return result;
+        }
+        try {
+            this.#auth.assertSession(result.value, now);
+        }
+        catch (error) {
+            if (error instanceof errors_1.AuthError) {
+                return {
+                    ok: false,
+                    error,
+                };
+            }
+            return {
+                ok: false,
+                error: new errors_1.AuthError("internal_error", {
+                    details: {
+                        policy: "authentication",
+                        subject: result.value.id.toString(),
+                    },
+                    cause: error instanceof Error ? error : undefined,
+                }),
+            };
+        }
+        return result;
+    }
+    /**
+     * @inheritdoc
+     */
+    async issueTokens(input, now) {
+        // 1. Create session
+        const session = await this.#auth.createSession(input, now);
+        if (!session.ok) {
+            return session;
+        }
+        // 2. Sign tokens
+        const accessToken = await this.#tokens.signAccessToken(session.value);
+        if (!accessToken.ok) {
+            return accessToken;
+        }
+        // 3. Sign refresh token
+        const refreshToken = await this.#tokens.signRefreshToken(session.value);
+        if (!refreshToken.ok) {
+            return refreshToken;
+        }
+        return {
+            ok: true,
+            value: {
+                session: session.value,
+                accessToken: accessToken.value,
+                refreshToken: refreshToken.value,
+            },
+        };
+    }
+    /**
+     * @inheritdoc
+     */
+    async refreshTokens(token, id, now) {
+        // 1. Verify refresh token
+        const verified = await this.#tokens.verifyRefreshToken(token);
+        if (!verified.ok) {
+            return verified;
+        }
+        // 2. Refresh session
+        const session = await this.#auth.refreshSession({
+            id,
+            originalId: verified.value.id,
+        }, now);
+        if (!session.ok) {
+            return session;
+        }
+        // 3. Sign new tokens
+        const accessToken = await this.#tokens.signAccessToken(session.value);
+        if (!accessToken.ok) {
+            return accessToken;
+        }
+        // 4. Sign new refresh token
+        const refreshToken = await this.#tokens.signRefreshToken(session.value);
+        if (!refreshToken.ok) {
+            return refreshToken;
+        }
+        return {
+            ok: true,
+            value: {
+                session: session.value,
+                accessToken: accessToken.value,
+                refreshToken: refreshToken.value,
+            },
+        };
+    }
+}
+exports.DefaultAuthTokenFacade = DefaultAuthTokenFacade;
+//# sourceMappingURL=default.js.map

package/dist/cjs/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DefaultAuthTokenFacade = void 0;
+var default_js_1 = require("./facade/default.js");
+Object.defineProperty(exports, "DefaultAuthTokenFacade", { enumerable: true, get: function () { return default_js_1.DefaultAuthTokenFacade; } });
+//# sourceMappingURL=index.js.map

package/dist/esm/contracts/envelope.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=envelope.js.map

package/dist/esm/contracts/facade.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=facade.js.map

package/dist/esm/facade/default.js

@@ -0,0 +1,114 @@
+import { AuthError } from "@comity/auth/errors";
+/**
+ * Default implementation of the AuthTokenFacade.
+ */
+export class DefaultAuthTokenFacade {
+    /**  */
+    #auth;
+    /**  */
+    #tokens;
+    /**
+     * @param auth - The authentication facade to use for session management
+     * @param tokens - The token service to use for token operations
+     */
+    constructor(auth, tokens) {
+        this.#auth = auth;
+        this.#tokens = tokens;
+    }
+    /**
+     * @inheritdoc
+     */
+    async authenticate(token, now) {
+        const result = await this.#tokens.verifyAccessToken(token);
+        if (!result.ok) {
+            return result;
+        }
+        try {
+            this.#auth.assertSession(result.value, now);
+        }
+        catch (error) {
+            if (error instanceof AuthError) {
+                return {
+                    ok: false,
+                    error,
+                };
+            }
+            return {
+                ok: false,
+                error: new AuthError("internal_error", {
+                    details: {
+                        policy: "authentication",
+                        subject: result.value.id.toString(),
+                    },
+                    cause: error instanceof Error ? error : undefined,
+                }),
+            };
+        }
+        return result;
+    }
+    /**
+     * @inheritdoc
+     */
+    async issueTokens(input, now) {
+        // 1. Create session
+        const session = await this.#auth.createSession(input, now);
+        if (!session.ok) {
+            return session;
+        }
+        // 2. Sign tokens
+        const accessToken = await this.#tokens.signAccessToken(session.value);
+        if (!accessToken.ok) {
+            return accessToken;
+        }
+        // 3. Sign refresh token
+        const refreshToken = await this.#tokens.signRefreshToken(session.value);
+        if (!refreshToken.ok) {
+            return refreshToken;
+        }
+        return {
+            ok: true,
+            value: {
+                session: session.value,
+                accessToken: accessToken.value,
+                refreshToken: refreshToken.value,
+            },
+        };
+    }
+    /**
+     * @inheritdoc
+     */
+    async refreshTokens(token, id, now) {
+        // 1. Verify refresh token
+        const verified = await this.#tokens.verifyRefreshToken(token);
+        if (!verified.ok) {
+            return verified;
+        }
+        // 2. Refresh session
+        const session = await this.#auth.refreshSession({
+            id,
+            originalId: verified.value.id,
+        }, now);
+        if (!session.ok) {
+            return session;
+        }
+        // 3. Sign new tokens
+        const accessToken = await this.#tokens.signAccessToken(session.value);
+        if (!accessToken.ok) {
+            return accessToken;
+        }
+        // 4. Sign new refresh token
+        const refreshToken = await this.#tokens.signRefreshToken(session.value);
+        if (!refreshToken.ok) {
+            return refreshToken;
+        }
+        return {
+            ok: true,
+            value: {
+                session: session.value,
+                accessToken: accessToken.value,
+                refreshToken: refreshToken.value,
+            },
+        };
+    }
+}
+//# sourceMappingURL=default.js.map

package/dist/esm/index.js

@@ -0,0 +1,2 @@
+export { DefaultAuthTokenFacade } from "./facade/default.js";
+//# sourceMappingURL=index.js.map

package/dist/types/contracts/envelope.d.ts

@@ -0,0 +1,12 @@
+import type { AuthSession } from "@comity/auth";
+/**
+ * Data structure returned when multiple tokens are issued.
+ */
+export interface AuthTokenEnvelope {
+    /** The issued access token. */
+    readonly accessToken: string;
+    /** The issued refresh token, if applicable. */
+    readonly refreshToken?: string;
+    /** The session associated with the issued tokens. */
+    readonly session: AuthSession;
+}

package/dist/types/contracts/facade.d.ts

@@ -0,0 +1,58 @@
+import type { AuthSession, AuthSessionAssuranceInput, AuthSessionId, AuthSessionTransport } from "@comity/auth";
+import type { AuthError } from "@comity/auth/errors";
+import type { Result } from "@comity/primitives/result";
+import type { AuthTokenEnvelope } from "./envelope.js";
+/**
+ * Input data required to issue new tokens, including session creation parameters and optional refresh capabilities.
+ */
+export interface IssueTokensInput extends AuthSessionAssuranceInput {
+    /** Session identifier */
+    readonly id: AuthSessionId;
+    /** Hard expiration */
+    readonly expiresAt?: number;
+    /** Session transport mechanism */
+    readonly transport: AuthSessionTransport;
+    /** Refresh capabilities */
+    readonly refresh?: false | number;
+    /** Step-up parent */
+    readonly parent?: AuthSessionId;
+    /** Authorization scopes */
+    readonly scopes?: readonly string[];
+}
+/**
+ * AuthTokenFacade provides a simplified interface for authentication operations, abstracting away the underlying complexities of token management and session handling.
+ */
+export interface AuthTokenFacade {
+    /**
+     * Authenticates a request by verifying the access token and
+     * asserting that the underlying session is still valid.
+     * (Verify Token -> Get Session -> Assert Session)
+     *
+     * @param token - The access token to authenticate
+     * @param now - Current timestamp for session validation
+     *
+     * @returns The result of the authentication, containing either the auth session or an auth error
+     */
+    authenticate(token: string, now: number): Promise<Result<AuthSession, AuthError, "ok">>;
+    /**
+     * Issues a new set of tokens for a given session creation input.
+     * (Create Session -> Sign Access Token -> Sign Refresh Token)
+     *
+     * @param input - The input data required to create a new session
+     * @param now - Current timestamp for session creation
+     *
+     * @returns The result of the token issuance, containing either the token envelope or an auth error
+     */
+    issueTokens(input: IssueTokensInput, now: number): Promise<Result<AuthTokenEnvelope, AuthError, "ok">>;
+    /**
+     * Refreshes an existing session using a refresh token.
+     * (Verify Refresh Token -> Refresh Session -> Sign New Tokens)
+     *
+     * @param token - The refresh token to use for refreshing the session
+     * @param id - The new session ID to assign to the refreshed session
+     * @param now - Current timestamp for session refresh
+     *
+     * @returns The result of the token refresh, containing either the new token envelope or an auth error
+     */
+    refreshTokens(token: string, id: AuthSessionId, now: number): Promise<Result<AuthTokenEnvelope, AuthError, "ok">>;
+}

package/dist/types/facade/default.d.ts

@@ -0,0 +1,28 @@
+import type { AuthFacade, AuthSession, AuthSessionId, AuthTokenService } from "@comity/auth";
+import type { Result } from "@comity/primitives/result";
+import type { AuthTokenEnvelope } from "../contracts/envelope";
+import type { AuthTokenFacade, IssueTokensInput } from "../contracts/facade";
+import { AuthError } from "@comity/auth/errors";
+/**
+ * Default implementation of the AuthTokenFacade.
+ */
+export declare class DefaultAuthTokenFacade implements AuthTokenFacade {
+    #private;
+    /**
+     * @param auth - The authentication facade to use for session management
+     * @param tokens - The token service to use for token operations
+     */
+    constructor(auth: AuthFacade, tokens: AuthTokenService);
+    /**
+     * @inheritdoc
+     */
+    authenticate(token: string, now: number): Promise<Result<AuthSession, AuthError, "ok">>;
+    /**
+     * @inheritdoc
+     */
+    issueTokens(input: IssueTokensInput, now: number): Promise<Result<AuthTokenEnvelope, AuthError, "ok">>;
+    /**
+     * @inheritdoc
+     */
+    refreshTokens(token: string, id: AuthSessionId, now: number): Promise<Result<AuthTokenEnvelope, AuthError, "ok">>;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,3 @@
+export type { AuthTokenEnvelope } from "./contracts/envelope.js";
+export type { AuthTokenFacade, IssueTokensInput } from "./contracts/facade.js";
+export { DefaultAuthTokenFacade } from "./facade/default.js";

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@comity/auth-tokens",
+  "version": "0.9.0",
+  "description": "Token envelope and facade primitives for Comity.",
+  "type": "module",
+  "private": false,
+  "author": "Filippo Bovo <hello@filippobovo.com>",
+  "license": "MIT",
+  "comity": {
+    "layer": "core"
+  },
+  "homepage": "https://github.com/comityjs/framework#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/comityjs/framework.git"
+  },
+  "bugs": {
+    "url": "https://github.com/comityjs/framework/issues"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "keywords": [
+    "comity",
+    "comityjs",
+    "auth",
+    "authentication",
+    "jwt",
+    "refresh-token",
+    "security",
+    "session",
+    "token",
+    "typescript"
+  ],
+  "files": [
+    "./dist",
+    "!./dist/**/*.map"
+  ],
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "typesVersions": {
+    "*": {}
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "@comity/auth": "0.9.0",
+    "@comity/primitives": "0.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.4",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "node ../../scripts/build.mjs",
+    "dev": "node ../../scripts/build.mjs --watch",
+    "test": "vitest run --coverage",
+    "type-check": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint --ext .ts src"
+  }
+}