@heyatom/bastion-client 0.1.2 → 0.2.0

package/README.md

@@ -62,6 +62,15 @@ export class AdminController {
 
 Bastion stores app events as `<serviceSlug>.<event>` — send the bare `resource.action`.
 
+## App backends: verifying your users' tokens
+
+```ts
+// BastionJwksService.verifyUserToken(token): a user session token minted for this app
+// (rejects machine tokens, checks aud + appSlug === serviceSlug, requires sub). Build your
+// own guard on it — cookie extraction, suspension, age gate are the app's business.
+// Core equivalent: assertUserTokenFor(await verifier.verify(token), 'dbd-builds').
+```
+
 ## Without NestJS
 
 ```ts

package/dist/cjs/core/errors.d.ts

@@ -1,4 +1,4 @@
-export type TokenErrorCode = 'malformed' | 'missing_kid' | 'unknown_kid' | 'invalid';
+export type TokenErrorCode = 'malformed' | 'missing_kid' | 'unknown_kid' | 'invalid' | 'not_user_token' | 'wrong_app';
 /** Verification failure. `code` is safe to log; the message is safe to return to the caller. */
 export declare class BastionTokenError extends Error {
     readonly code: TokenErrorCode;

package/dist/cjs/core/types.d.ts

@@ -29,6 +29,14 @@ export interface ServiceClientJwtPayload extends CommonClaims {
     scopes: string[];
 }
 export type BastionJwtPayload = UserJwtPayload | ServiceClientJwtPayload;
+/**
+ * For an app backend that accepts its *users'* tokens: the payload must be a
+ * user token (machine tokens are rejected whatever their scopes), minted for
+ * this app — Bastion sets `aud` and `appSlug` to the app slug at issuance, and
+ * one signing key serves the whole fleet, so a valid signature alone proves
+ * nothing about which app the session belongs to.
+ */
+export declare function assertUserTokenFor(payload: BastionJwtPayload, appSlug: string): UserJwtPayload;
 export declare function isServiceClientToken(payload: BastionJwtPayload): payload is ServiceClientJwtPayload;
 export interface TokenResponse {
     accessToken: string;

package/dist/cjs/core/types.js

@@ -1,7 +1,27 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.silentLogger = void 0;
+exports.assertUserTokenFor = assertUserTokenFor;
 exports.isServiceClientToken = isServiceClientToken;
+const errors_js_1 = require("./errors.js");
+/**
+ * For an app backend that accepts its *users'* tokens: the payload must be a
+ * user token (machine tokens are rejected whatever their scopes), minted for
+ * this app — Bastion sets `aud` and `appSlug` to the app slug at issuance, and
+ * one signing key serves the whole fleet, so a valid signature alone proves
+ * nothing about which app the session belongs to.
+ */
+function assertUserTokenFor(payload, appSlug) {
+    if (payload.type !== undefined) {
+        throw new errors_js_1.BastionTokenError('not_user_token', 'Service token not allowed');
+    }
+    if (payload.aud !== appSlug || payload.appSlug !== appSlug) {
+        throw new errors_js_1.BastionTokenError('wrong_app', 'Invalid app context');
+    }
+    if (!payload.sub)
+        throw new errors_js_1.BastionTokenError('wrong_app', 'Token without subject');
+    return payload;
+}
 function isServiceClientToken(payload) {
     return payload.type === 'service_client';
 }

package/dist/cjs/nest/bastion-jwks.service.d.ts

@@ -1,8 +1,15 @@
-import type { BastionJwtPayload } from '../core/types.js';
+import { type BastionJwtPayload, type UserJwtPayload } from '../core/types.js';
 import { type BastionModuleOptions } from './options.js';
 /** Verifies inbound Bastion tokens against the cached JWKS. Throws `UnauthorizedException` on any failure. */
 export declare class BastionJwksService {
     private readonly verifier;
+    private readonly appSlug;
     constructor(options: BastionModuleOptions);
     verify(token: string): Promise<BastionJwtPayload>;
+    /**
+     * A *user* session token issued for this app (`options.serviceSlug` is the
+     * app's own slug). What an app backend puts behind its own auth guard —
+     * cookie extraction, suspension, age gate stay the app's business.
+     */
+    verifyUserToken(token: string): Promise<UserJwtPayload>;
 }

package/dist/cjs/nest/bastion-jwks.service.js

@@ -17,12 +17,15 @@ exports.BastionJwksService = void 0;
 const common_1 = require("@nestjs/common");
 const jwks_verifier_js_1 = require("../core/jwks-verifier.js");
 const errors_js_1 = require("../core/errors.js");
+const types_js_1 = require("../core/types.js");
 const options_js_1 = require("./options.js");
 const nest_logger_js_1 = require("./nest-logger.js");
 /** Verifies inbound Bastion tokens against the cached JWKS. Throws `UnauthorizedException` on any failure. */
 let BastionJwksService = BastionJwksService_1 = class BastionJwksService {
     verifier;
+    appSlug;
     constructor(options) {
+        this.appSlug = options.serviceSlug;
         this.verifier = new jwks_verifier_js_1.JwksVerifier({
             baseUrl: options.baseUrl,
             ttlMs: options.jwksTtlMs,
@@ -40,6 +43,22 @@ let BastionJwksService = BastionJwksService_1 = class BastionJwksService {
             throw err;
         }
     }
+    /**
+     * A *user* session token issued for this app (`options.serviceSlug` is the
+     * app's own slug). What an app backend puts behind its own auth guard —
+     * cookie extraction, suspension, age gate stay the app's business.
+     */
+    async verifyUserToken(token) {
+        const payload = await this.verify(token);
+        try {
+            return (0, types_js_1.assertUserTokenFor)(payload, this.appSlug);
+        }
+        catch (err) {
+            if (err instanceof errors_js_1.BastionTokenError)
+                throw new common_1.UnauthorizedException(err.message);
+            throw err;
+        }
+    }
 };
 exports.BastionJwksService = BastionJwksService;
 exports.BastionJwksService = BastionJwksService = BastionJwksService_1 = __decorate([

package/dist/esm/core/errors.d.ts

@@ -1,4 +1,4 @@
-export type TokenErrorCode = 'malformed' | 'missing_kid' | 'unknown_kid' | 'invalid';
+export type TokenErrorCode = 'malformed' | 'missing_kid' | 'unknown_kid' | 'invalid' | 'not_user_token' | 'wrong_app';
 /** Verification failure. `code` is safe to log; the message is safe to return to the caller. */
 export declare class BastionTokenError extends Error {
     readonly code: TokenErrorCode;

package/dist/esm/core/types.d.ts

@@ -29,6 +29,14 @@ export interface ServiceClientJwtPayload extends CommonClaims {
     scopes: string[];
 }
 export type BastionJwtPayload = UserJwtPayload | ServiceClientJwtPayload;
+/**
+ * For an app backend that accepts its *users'* tokens: the payload must be a
+ * user token (machine tokens are rejected whatever their scopes), minted for
+ * this app — Bastion sets `aud` and `appSlug` to the app slug at issuance, and
+ * one signing key serves the whole fleet, so a valid signature alone proves
+ * nothing about which app the session belongs to.
+ */
+export declare function assertUserTokenFor(payload: BastionJwtPayload, appSlug: string): UserJwtPayload;
 export declare function isServiceClientToken(payload: BastionJwtPayload): payload is ServiceClientJwtPayload;
 export interface TokenResponse {
     accessToken: string;

package/dist/esm/core/types.js

@@ -1,3 +1,22 @@
+import { BastionTokenError } from './errors.js';
+/**
+ * For an app backend that accepts its *users'* tokens: the payload must be a
+ * user token (machine tokens are rejected whatever their scopes), minted for
+ * this app — Bastion sets `aud` and `appSlug` to the app slug at issuance, and
+ * one signing key serves the whole fleet, so a valid signature alone proves
+ * nothing about which app the session belongs to.
+ */
+export function assertUserTokenFor(payload, appSlug) {
+    if (payload.type !== undefined) {
+        throw new BastionTokenError('not_user_token', 'Service token not allowed');
+    }
+    if (payload.aud !== appSlug || payload.appSlug !== appSlug) {
+        throw new BastionTokenError('wrong_app', 'Invalid app context');
+    }
+    if (!payload.sub)
+        throw new BastionTokenError('wrong_app', 'Token without subject');
+    return payload;
+}
 export function isServiceClientToken(payload) {
     return payload.type === 'service_client';
 }

package/dist/esm/nest/bastion-jwks.service.d.ts

@@ -1,8 +1,15 @@
-import type { BastionJwtPayload } from '../core/types.js';
+import { type BastionJwtPayload, type UserJwtPayload } from '../core/types.js';
 import { type BastionModuleOptions } from './options.js';
 /** Verifies inbound Bastion tokens against the cached JWKS. Throws `UnauthorizedException` on any failure. */
 export declare class BastionJwksService {
     private readonly verifier;
+    private readonly appSlug;
     constructor(options: BastionModuleOptions);
     verify(token: string): Promise<BastionJwtPayload>;
+    /**
+     * A *user* session token issued for this app (`options.serviceSlug` is the
+     * app's own slug). What an app backend puts behind its own auth guard —
+     * cookie extraction, suspension, age gate stay the app's business.
+     */
+    verifyUserToken(token: string): Promise<UserJwtPayload>;
 }

package/dist/esm/nest/bastion-jwks.service.js

@@ -14,12 +14,15 @@ var BastionJwksService_1;
 import { Inject, Injectable, UnauthorizedException } from '@nestjs/common';
 import { JwksVerifier } from '../core/jwks-verifier.js';
 import { BastionTokenError } from '../core/errors.js';
+import { assertUserTokenFor } from '../core/types.js';
 import { BASTION_OPTIONS } from './options.js';
 import { nestLogger } from './nest-logger.js';
 /** Verifies inbound Bastion tokens against the cached JWKS. Throws `UnauthorizedException` on any failure. */
 let BastionJwksService = BastionJwksService_1 = class BastionJwksService {
     verifier;
+    appSlug;
     constructor(options) {
+        this.appSlug = options.serviceSlug;
         this.verifier = new JwksVerifier({
             baseUrl: options.baseUrl,
             ttlMs: options.jwksTtlMs,
@@ -37,6 +40,22 @@ let BastionJwksService = BastionJwksService_1 = class BastionJwksService {
             throw err;
         }
     }
+    /**
+     * A *user* session token issued for this app (`options.serviceSlug` is the
+     * app's own slug). What an app backend puts behind its own auth guard —
+     * cookie extraction, suspension, age gate stay the app's business.
+     */
+    async verifyUserToken(token) {
+        const payload = await this.verify(token);
+        try {
+            return assertUserTokenFor(payload, this.appSlug);
+        }
+        catch (err) {
+            if (err instanceof BastionTokenError)
+                throw new UnauthorizedException(err.message);
+            throw err;
+        }
+    }
 };
 BastionJwksService = BastionJwksService_1 = __decorate([
     Injectable(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heyatom/bastion-client",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Consumer SDK for the Bastion identity provider: JWKS verification, service-client auth, audit writes, NestJS guards",
   "license": "MIT",
   "author": "Andrea Tombolato <hey@heyatom.dev> (https://heyatom.dev)",