@spinajs/rbac-http-token 2.0.507

package/lib/cjs/generator.js

@@ -0,0 +1,42 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SecureRandomTokenProvider = void 0;
+const crypto_1 = require("crypto");
+const di_1 = require("@spinajs/di");
+const configuration_1 = require("@spinajs/configuration");
+const interfaces_js_1 = require("./interfaces.js");
+/**
+ * Default token algorithm: `<prefix>` + N crypto-random bytes base64url encoded.
+ * The stable prefix makes leaked tokens findable by secret scanners.
+ */
+let SecureRandomTokenProvider = class SecureRandomTokenProvider extends interfaces_js_1.AccessTokenGenerationProvider {
+    async generate() {
+        const plaintext = `${this.Prefix}${(0, crypto_1.randomBytes)(this.Length).toString('base64url')}`;
+        return { Plaintext: plaintext, Hash: this.hash(plaintext) };
+    }
+    hash(plaintext) {
+        return (0, crypto_1.createHash)('sha256').update(plaintext).digest('hex');
+    }
+};
+exports.SecureRandomTokenProvider = SecureRandomTokenProvider;
+__decorate([
+    (0, configuration_1.Config)('rbac.token.prefix', { defaultValue: 'spt_' }),
+    __metadata("design:type", String)
+], SecureRandomTokenProvider.prototype, "Prefix", void 0);
+__decorate([
+    (0, configuration_1.Config)('rbac.token.length', { defaultValue: 32 }),
+    __metadata("design:type", Number)
+], SecureRandomTokenProvider.prototype, "Length", void 0);
+exports.SecureRandomTokenProvider = SecureRandomTokenProvider = __decorate([
+    (0, di_1.Injectable)(interfaces_js_1.AccessTokenGenerationProvider)
+], SecureRandomTokenProvider);
+//# sourceMappingURL=generator.js.map

package/lib/cjs/generator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generator.js","sourceRoot":"","sources":["../../src/generator.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,mCAAiD;AACjD,oCAAyC;AACzC,0DAAgD;AAEhD,mDAAiF;AAEjF;;;GAGG;AAEI,IAAM,yBAAyB,GAA/B,MAAM,yBAA0B,SAAQ,6CAA6B;IAOnE,KAAK,CAAC,QAAQ;QACnB,MAAM,SAAS,GAAG,GAAG,IAAI,CAAC,MAAM,GAAG,IAAA,oBAAW,EAAC,IAAI,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;QACpF,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;IAC9D,CAAC;IAEM,IAAI,CAAC,SAAiB;QAC3B,OAAO,IAAA,mBAAU,EAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC9D,CAAC;CACF,CAAA;;AAbW;IADT,IAAA,sBAAM,EAAC,mBAAmB,EAAE,EAAE,YAAY,EAAE,MAAM,EAAE,CAAC;;yDAC7B;AAGf;IADT,IAAA,sBAAM,EAAC,mBAAmB,EAAE,EAAE,YAAY,EAAE,EAAE,EAAE,CAAC;;yDACzB;oCALd,yBAAyB;IADrC,IAAA,eAAU,EAAC,6CAA6B,CAAC;GAC7B,yBAAyB,CAerC"}

package/lib/cjs/index.d.ts

@@ -0,0 +1,20 @@
+import './generator.js';
+import './middlewares.js';
+export * from './interfaces.js';
+export * from './models/AccessToken.js';
+export * from './migrations/RbacHttpTokenInitial_2026_08_11_01_00_00.js';
+export * from './generator.js';
+export * from './events/index.js';
+export * from './actions.js';
+export * from './middlewares.js';
+export * from './policies/TokenPolicy.js';
+export * from './policies/NoTokenAuthPolicy.js';
+export * from './policies/NoImpersonationPolicy.js';
+export * from './controllers/AccessTokenController.js';
+export * from './dto/create-token-dto.js';
+export * from './cli/CreateToken.js';
+export * from './cli/DeleteToken.js';
+export * from './cli/GrantTokenRole.js';
+export * from './cli/RevokeTokenRole.js';
+export * from './cli/DeleteExpiredTokens.js';
+//# sourceMappingURL=index.d.ts.map

package/lib/cjs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,gBAAgB,CAAC;AACxB,OAAO,kBAAkB,CAAC;AAE1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,yBAAyB,CAAC;AACxC,cAAc,0DAA0D,CAAC;AACzE,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iCAAiC,CAAC;AAChD,cAAc,qCAAqC,CAAC;AACpD,cAAc,wCAAwC,CAAC;AACvD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC;AACzC,cAAc,8BAA8B,CAAC"}

package/lib/cjs/index.js

@@ -0,0 +1,39 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// Side effect imports - these modules register Injectables ( the token
+// generator and the token authorization middleware ) the moment they are
+// loaded, so they must run even if a consumer imports nothing from them.
+require("./generator.js");
+require("./middlewares.js");
+__exportStar(require("./interfaces.js"), exports);
+__exportStar(require("./models/AccessToken.js"), exports);
+__exportStar(require("./migrations/RbacHttpTokenInitial_2026_08_11_01_00_00.js"), exports);
+__exportStar(require("./generator.js"), exports);
+__exportStar(require("./events/index.js"), exports);
+__exportStar(require("./actions.js"), exports);
+__exportStar(require("./middlewares.js"), exports);
+__exportStar(require("./policies/TokenPolicy.js"), exports);
+__exportStar(require("./policies/NoTokenAuthPolicy.js"), exports);
+__exportStar(require("./policies/NoImpersonationPolicy.js"), exports);
+__exportStar(require("./controllers/AccessTokenController.js"), exports);
+__exportStar(require("./dto/create-token-dto.js"), exports);
+__exportStar(require("./cli/CreateToken.js"), exports);
+__exportStar(require("./cli/DeleteToken.js"), exports);
+__exportStar(require("./cli/GrantTokenRole.js"), exports);
+__exportStar(require("./cli/RevokeTokenRole.js"), exports);
+__exportStar(require("./cli/DeleteExpiredTokens.js"), exports);
+//# sourceMappingURL=index.js.map

package/lib/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,uEAAuE;AACvE,yEAAyE;AACzE,yEAAyE;AACzE,0BAAwB;AACxB,4BAA0B;AAE1B,kDAAgC;AAChC,0DAAwC;AACxC,2FAAyE;AACzE,iDAA+B;AAC/B,oDAAkC;AAClC,+CAA6B;AAC7B,mDAAiC;AACjC,4DAA0C;AAC1C,kEAAgD;AAChD,sEAAoD;AACpD,yEAAuD;AACvD,4DAA0C;AAC1C,uDAAqC;AACrC,uDAAqC;AACrC,0DAAwC;AACxC,2DAAyC;AACzC,+DAA6C"}

package/lib/cjs/interfaces.d.ts

@@ -0,0 +1,57 @@
+export interface IGeneratedToken {
+    /**
+     * Full token as handed to the user, e.g. `spt_<base64url>`. Shown exactly once.
+     */
+    Plaintext: string;
+    /**
+     * SHA-256 hex digest of the plaintext - the only thing that is persisted.
+     */
+    Hash: string;
+}
+/**
+ * Token generation algorithm. Replaceable via config
+ * `rbac.token.generation.service` - same pattern as `rbac.password.service`.
+ */
+export declare abstract class AccessTokenGenerationProvider {
+    /**
+     * Generates a fresh token. Plaintext leaves the server once; only the hash is stored.
+     */
+    abstract generate(): Promise<IGeneratedToken>;
+    /**
+     * Deterministic hash of a presented plaintext, used for DB lookup.
+     */
+    abstract hash(plaintext: string): string;
+}
+/**
+ * Marker stored on request async storage when a request was authenticated
+ * with an access token instead of a session.
+ */
+export interface ITokenAuthInfo {
+    /**
+     * Uuid of the AccessToken row - safe to log; never the token itself.
+     */
+    Uuid: string;
+}
+declare module '@spinajs/rbac' {
+    interface IRbacAsyncStorage {
+        /**
+         * Set by TokenAuthMiddleware when the request carries a valid access token.
+         */
+        TokenAuth?: ITokenAuthInfo;
+    }
+}
+/**
+ * The http request-local storage is a SEPARATE interface from rbac's
+ * `IRbacAsyncStorage` ( `@spinajs/rbac-http` augments it the same way with
+ * User / Session / ActiveRole ), so the marker has to be declared on both -
+ * the one above for rbac's execution context, this one for `req.storage`.
+ */
+declare module '@spinajs/http' {
+    interface IActionLocalStoregeContext {
+        /**
+         * Set by TokenAuthMiddleware when the request carries a valid access token.
+         */
+        TokenAuth?: ITokenAuthInfo;
+    }
+}
+//# sourceMappingURL=interfaces.d.ts.map

package/lib/cjs/interfaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../../src/interfaces.ts"],"names":[],"mappings":"AAUA,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,8BAAsB,6BAA6B;IACjD;;OAEG;IACH,SAAgB,QAAQ,IAAI,OAAO,CAAC,eAAe,CAAC,CAAC;IAErD;;OAEG;IACH,SAAgB,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;CACjD;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;CACd;AAED,OAAO,QAAQ,eAAe,CAAC;IAC7B,UAAU,iBAAiB;QACzB;;WAEG;QACH,SAAS,CAAC,EAAE,cAAc,CAAC;KAC5B;CACF;AAED;;;;;GAKG;AACH,OAAO,QAAQ,eAAe,CAAC;IAC7B,UAAU,0BAA0B;QAClC;;WAEG;QACH,SAAS,CAAC,EAAE,cAAc,CAAC;KAC5B;CACF"}

package/lib/cjs/interfaces.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AccessTokenGenerationProvider = void 0;
+/**
+ * Token generation algorithm. Replaceable via config
+ * `rbac.token.generation.service` - same pattern as `rbac.password.service`.
+ */
+class AccessTokenGenerationProvider {
+}
+exports.AccessTokenGenerationProvider = AccessTokenGenerationProvider;
+//# sourceMappingURL=interfaces.js.map

package/lib/cjs/interfaces.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interfaces.js","sourceRoot":"","sources":["../../src/interfaces.ts"],"names":[],"mappings":";;;AAsBA;;;GAGG;AACH;CAUC"}

package/lib/cjs/middlewares.d.ts

@@ -0,0 +1,76 @@
+import * as express from 'express';
+import { Log } from '@spinajs/log';
+import { Request as sRequest, ServerMiddleware } from '@spinajs/http';
+import { User } from '@spinajs/rbac';
+import './interfaces.js';
+/**
+ * Authenticates requests carrying an access token in `Authorization: Bearer`
+ * or the configured fallback header. Runs AFTER RbacMiddleware ( Order 0 )
+ * so a session, when present, always wins - a request cannot mix both.
+ *
+ * On success `req.storage.User` carries the owner with Role narrowed to the
+ * token's effective roles, so every downstream permission check ( RbacPolicy
+ * helpers, orm rbac query middleware, ownership ) works unchanged.
+ *
+ * `req.storage.ActiveRole` is deliberately CLEARED, and that is load bearing.
+ * Both consumers of the field resolve the roles to authorize with as
+ * `ActiveRole ? [ActiveRole] : User.Role` ( `checkRoutePermission` in
+ * `rbac-http/src/policies/RbacPolicy.ts`, and the orm rbac query middleware in
+ * `rbac/src/middleware.ts` ), so whatever single role sits there collapses the
+ * request down to that one role.
+ *
+ * A session can afford that collapse because it can switch its active role at
+ * runtime ( `POST /auth/active-role` ), so the narrowing is both deliberate and
+ * reversible. A token carries no session and has no way to switch, so picking
+ * one of its roles - the first, arbitrarily - would permanently authorize the
+ * token with a strict subset of what it was issued for: a token holding
+ * `[ 'user', 'admin' ]` would never satisfy an admin-only grant.
+ *
+ * Leaving it undefined makes both consumers fall back to `User.Role`, which the
+ * narrowing above has ALREADY reduced to exactly the effective role set - the
+ * intersection of what the token carries and its owner still holds. That is the
+ * correct authorization scope for a token, and nothing wider.
+ *
+ * The field has to be assigned `undefined` rather than skipped: `RbacMiddleware`
+ * runs first and, on a session-less request, stamps the GUEST account's first
+ * role into it, which would otherwise survive into the token's own request.
+ *
+ * Never throws: an invalid token leaves the request as guest and lets the
+ * route's policy produce the rejection.
+ */
+export declare class TokenAuthMiddleware extends ServerMiddleware {
+    protected Log: Log;
+    protected HeaderName: string;
+    protected LastUsedUpdateInterval: number;
+    constructor();
+    before(): (req: sRequest, res: express.Response, next: express.NextFunction) => void;
+    after(): null;
+    /**
+     * Narrows the loaded owner to the token's effective roles WITHOUT letting the
+     * narrowing reach the database.
+     *
+     * `Role` is a real `@Set()` column, and this very instance is what controllers
+     * receive through the `@User()` route argument. `update()` writes whatever
+     * differs from the model's snapshot, so a controller doing an unrelated edit
+     * ( "change my login" ) and calling `.update()` would silently persist the
+     * narrowed list - permanently stripping every role the token did not carry.
+     *
+     * Re-taking the snapshot right after the narrowing makes it invisible to that
+     * diff: the instance then behaves exactly like a freshly loaded row whose roles
+     * happen to be the effective ones, and a later `.update()` writes only what the
+     * controller itself changed. The full instance is kept rather than copied so
+     * that `Id`, `Password`, the `Metadata` relation and the prototype accessors
+     * ( `IsBanned`, `can()` ) all survive - `dehydrate()` drops the `@Hidden()`
+     * columns, so a dehydrate/rehydrate copy would arrive without `Id`.
+     *
+     * `takeSnapshot()` also discards the relation baselines, which the orm's
+     * subject builder needs to tell an already-persisted related row from a new
+     * one, so they are recorded again immediately.
+     */
+    protected narrowRoles(user: User, roles: string[]): User;
+    /**
+     * Bearer scheme first, configured fallback header second.
+     */
+    protected extract(req: sRequest): string | null;
+}
+//# sourceMappingURL=middlewares.d.ts.map

package/lib/cjs/middlewares.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middlewares.d.ts","sourceRoot":"","sources":["../../src/middlewares.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,OAAO,MAAM,SAAS,CAAC;AAGnC,OAAO,EAAE,GAAG,EAAU,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEtE,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAGrC,OAAO,iBAAiB,CAAC;AAQzB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,qBACa,mBAAoB,SAAQ,gBAAgB;IAEvD,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC;IAGnB,SAAS,CAAC,UAAU,EAAE,MAAM,CAAC;IAG7B,SAAS,CAAC,sBAAsB,EAAE,MAAM,CAAC;IAEzC,cAIC;IAEM,MAAM,IAAI,CAAC,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,OAAO,CAAC,QAAQ,EAAE,IAAI,EAAE,OAAO,CAAC,YAAY,KAAK,IAAI,CAkD1F;IAEM,KAAK,IAAI,IAAI,CAEnB;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,SAAS,CAAC,WAAW,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CASvD;IAED;;OAEG;IACH,SAAS,CAAC,OAAO,CAAC,GAAG,EAAE,QAAQ,GAAG,MAAM,GAAG,IAAI,CAgB9C;CACF"}

package/lib/cjs/middlewares.js

@@ -0,0 +1,181 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TokenAuthMiddleware = void 0;
+const di_1 = require("@spinajs/di");
+const configuration_1 = require("@spinajs/configuration");
+const log_1 = require("@spinajs/log");
+const http_1 = require("@spinajs/http");
+const exceptions_1 = require("@spinajs/exceptions");
+const actions_js_1 = require("./actions.js");
+require("./interfaces.js");
+/**
+ * `Authorization: Bearer <token>`. RFC 7235 makes the scheme name
+ * case-insensitive, and clients do send `bearer`.
+ */
+const BEARER_SCHEME = /^bearer\s+/i;
+/**
+ * Authenticates requests carrying an access token in `Authorization: Bearer`
+ * or the configured fallback header. Runs AFTER RbacMiddleware ( Order 0 )
+ * so a session, when present, always wins - a request cannot mix both.
+ *
+ * On success `req.storage.User` carries the owner with Role narrowed to the
+ * token's effective roles, so every downstream permission check ( RbacPolicy
+ * helpers, orm rbac query middleware, ownership ) works unchanged.
+ *
+ * `req.storage.ActiveRole` is deliberately CLEARED, and that is load bearing.
+ * Both consumers of the field resolve the roles to authorize with as
+ * `ActiveRole ? [ActiveRole] : User.Role` ( `checkRoutePermission` in
+ * `rbac-http/src/policies/RbacPolicy.ts`, and the orm rbac query middleware in
+ * `rbac/src/middleware.ts` ), so whatever single role sits there collapses the
+ * request down to that one role.
+ *
+ * A session can afford that collapse because it can switch its active role at
+ * runtime ( `POST /auth/active-role` ), so the narrowing is both deliberate and
+ * reversible. A token carries no session and has no way to switch, so picking
+ * one of its roles - the first, arbitrarily - would permanently authorize the
+ * token with a strict subset of what it was issued for: a token holding
+ * `[ 'user', 'admin' ]` would never satisfy an admin-only grant.
+ *
+ * Leaving it undefined makes both consumers fall back to `User.Role`, which the
+ * narrowing above has ALREADY reduced to exactly the effective role set - the
+ * intersection of what the token carries and its owner still holds. That is the
+ * correct authorization scope for a token, and nothing wider.
+ *
+ * The field has to be assigned `undefined` rather than skipped: `RbacMiddleware`
+ * runs first and, on a session-less request, stamps the GUEST account's first
+ * role into it, which would otherwise survive into the token's own request.
+ *
+ * Never throws: an invalid token leaves the request as guest and lets the
+ * route's policy produce the rejection.
+ */
+let TokenAuthMiddleware = class TokenAuthMiddleware extends http_1.ServerMiddleware {
+    constructor() {
+        super();
+        // After RbacMiddleware ( Order 0 ): session auth takes precedence.
+        this.Order = 1;
+    }
+    before() {
+        return async (req, res, next) => {
+            try {
+                // Session user already authenticated - tokens do not apply.
+                if (req.storage?.Session) {
+                    return next();
+                }
+                const plaintext = this.extract(req);
+                if (!plaintext) {
+                    return next();
+                }
+                let result;
+                try {
+                    result = await (0, actions_js_1.validateToken)(plaintext);
+                }
+                catch (err) {
+                    // Deliberately vague towards the client; specific in the log. The uuid
+                    // is what makes a rejection actionable ( "which key broke" ) and is
+                    // safe to write down - `validateToken` attaches it as `data.token` on
+                    // every failure past the lookup. The presented plaintext is NEVER
+                    // logged, here or anywhere else.
+                    const data = err instanceof exceptions_1.ErrorCode ? err.data : undefined;
+                    this.Log.warn(`Access token rejected: ${err.message}`, { Ip: req.ip, Token: data?.token });
+                    return next();
+                }
+                req.storage.User = this.narrowRoles(result.User, result.EffectiveRoles);
+                req.storage.TokenAuth = { Uuid: result.Token.Uuid };
+                // CLEARED, not merely left alone - see the class docblock for why a
+                // token must carry no active role at all. `RbacMiddleware` has already
+                // run by now and, finding no session, wrote the GUEST user's first role
+                // here ( `rbac-http/src/middlewares.ts`, the `else` branch ). Leaving
+                // that in place would authorize every token request as `guest`.
+                req.storage.ActiveRole = undefined;
+                // Token-authenticated responses must never land in a shared cache.
+                res.setHeader('Cache-Control', 'no-store');
+                // Fire-and-forget throttled usage stamp. A non-Error rejection has no
+                // `.message`; reading one off it would throw inside the handler and
+                // surface as an unhandled rejection.
+                void (0, actions_js_1.touchToken)(result.Token, this.LastUsedUpdateInterval).catch((err) => this.Log.warn(`Failed to update token LastUsedAt: ${err instanceof Error ? err.message : String(err)}`, { Token: result.Token.Uuid }));
+                next();
+            }
+            catch (err) {
+                next(err);
+            }
+        };
+    }
+    after() {
+        return null;
+    }
+    /**
+     * Narrows the loaded owner to the token's effective roles WITHOUT letting the
+     * narrowing reach the database.
+     *
+     * `Role` is a real `@Set()` column, and this very instance is what controllers
+     * receive through the `@User()` route argument. `update()` writes whatever
+     * differs from the model's snapshot, so a controller doing an unrelated edit
+     * ( "change my login" ) and calling `.update()` would silently persist the
+     * narrowed list - permanently stripping every role the token did not carry.
+     *
+     * Re-taking the snapshot right after the narrowing makes it invisible to that
+     * diff: the instance then behaves exactly like a freshly loaded row whose roles
+     * happen to be the effective ones, and a later `.update()` writes only what the
+     * controller itself changed. The full instance is kept rather than copied so
+     * that `Id`, `Password`, the `Metadata` relation and the prototype accessors
+     * ( `IsBanned`, `can()` ) all survive - `dehydrate()` drops the `@Hidden()`
+     * columns, so a dehydrate/rehydrate copy would arrive without `Id`.
+     *
+     * `takeSnapshot()` also discards the relation baselines, which the orm's
+     * subject builder needs to tell an already-persisted related row from a new
+     * one, so they are recorded again immediately.
+     */
+    narrowRoles(user, roles) {
+        user.Role = roles;
+        user.takeSnapshot();
+        for (const [name] of user.ModelDescriptor?.Relations ?? []) {
+            user.snapshotRelation(name);
+        }
+        return user;
+    }
+    /**
+     * Bearer scheme first, configured fallback header second.
+     */
+    extract(req) {
+        // A header sent twice arrives as an array. Anything that is not a single
+        // string is malformed and has to read as "no token presented" - calling
+        // `.startsWith` / `.trim` on it would throw, and this middleware is
+        // contractually not allowed to turn a bad request into a 500.
+        const header = (name) => {
+            const value = req.headers?.[name];
+            return typeof value === 'string' ? value : null;
+        };
+        const auth = header('authorization');
+        if (auth && BEARER_SCHEME.test(auth)) {
+            return auth.replace(BEARER_SCHEME, '').trim() || null;
+        }
+        return header(this.HeaderName.toLowerCase())?.trim() || null;
+    }
+};
+exports.TokenAuthMiddleware = TokenAuthMiddleware;
+__decorate([
+    (0, log_1.Logger)('rbac-http-token'),
+    __metadata("design:type", log_1.Log)
+], TokenAuthMiddleware.prototype, "Log", void 0);
+__decorate([
+    (0, configuration_1.Config)('rbac.token.headerName', { defaultValue: 'x-api-key' }),
+    __metadata("design:type", String)
+], TokenAuthMiddleware.prototype, "HeaderName", void 0);
+__decorate([
+    (0, configuration_1.Config)('rbac.token.lastUsedUpdateInterval', { defaultValue: 60 }),
+    __metadata("design:type", Number)
+], TokenAuthMiddleware.prototype, "LastUsedUpdateInterval", void 0);
+exports.TokenAuthMiddleware = TokenAuthMiddleware = __decorate([
+    (0, di_1.Injectable)(http_1.ServerMiddleware),
+    __metadata("design:paramtypes", [])
+], TokenAuthMiddleware);
+//# sourceMappingURL=middlewares.js.map

package/lib/cjs/middlewares.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"middlewares.js","sourceRoot":"","sources":["../../src/middlewares.ts"],"names":[],"mappings":"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"}

package/lib/cjs/migrations/RbacHttpTokenInitial_2026_08_11_01_00_00.d.ts

@@ -0,0 +1,6 @@
+import { OrmMigration, OrmDriver } from '@spinajs/orm';
+export declare class RbacHttpTokenInitial_2026_08_11_01_00_00 extends OrmMigration {
+    up(connection: OrmDriver): Promise<void>;
+    down(_connection: OrmDriver): Promise<void>;
+}
+//# sourceMappingURL=RbacHttpTokenInitial_2026_08_11_01_00_00.d.ts.map

package/lib/cjs/migrations/RbacHttpTokenInitial_2026_08_11_01_00_00.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RbacHttpTokenInitial_2026_08_11_01_00_00.d.ts","sourceRoot":"","sources":["../../../src/migrations/RbacHttpTokenInitial_2026_08_11_01_00_00.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,SAAS,EAAa,MAAM,cAAc,CAAC;AAElE,qBACa,wCAAyC,SAAQ,YAAY;IAC3D,EAAE,CAAC,UAAU,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAkBpD;IAGY,IAAI,CAAC,WAAW,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAG;CAC5D"}

package/lib/cjs/migrations/RbacHttpTokenInitial_2026_08_11_01_00_00.js

@@ -0,0 +1,38 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RbacHttpTokenInitial_2026_08_11_01_00_00 = void 0;
+/* eslint-disable @typescript-eslint/no-unused-vars */
+const orm_1 = require("@spinajs/orm");
+let RbacHttpTokenInitial_2026_08_11_01_00_00 = class RbacHttpTokenInitial_2026_08_11_01_00_00 extends orm_1.OrmMigration {
+    async up(connection) {
+        await connection.schema().createTable('rbac_access_tokens', (table) => {
+            table.int('Id').primaryKey().autoIncrement();
+            table.string('Uuid', 36).notNull();
+            table.string('Name', 128).notNull();
+            table.string('Token', 64).notNull();
+            table.string('Roles', 512).notNull();
+            table.dateTime('ExpiresAt');
+            table.dateTime('CreatedAt').notNull().default().dateTime();
+            table.dateTime('LastUsedAt');
+            table.int('user_id').notNull();
+            table.foreignKey('user_id').references('users', 'Id').cascade();
+        });
+        await connection.index().unique().table('rbac_access_tokens').name('access_token_hash_idx').columns(['Token']);
+        await connection.index().unique().table('rbac_access_tokens').name('access_token_uuid_idx').columns(['Uuid']);
+        await connection.index().table('rbac_access_tokens').name('access_token_user_idx').columns(['user_id']);
+        await connection.index().table('rbac_access_tokens').name('access_token_expires_idx').columns(['ExpiresAt']);
+    }
+    // eslint-disable-next-line @typescript-eslint/no-empty-function
+    async down(_connection) { }
+};
+exports.RbacHttpTokenInitial_2026_08_11_01_00_00 = RbacHttpTokenInitial_2026_08_11_01_00_00;
+exports.RbacHttpTokenInitial_2026_08_11_01_00_00 = RbacHttpTokenInitial_2026_08_11_01_00_00 = __decorate([
+    (0, orm_1.Migration)('default')
+], RbacHttpTokenInitial_2026_08_11_01_00_00);
+//# sourceMappingURL=RbacHttpTokenInitial_2026_08_11_01_00_00.js.map

package/lib/cjs/migrations/RbacHttpTokenInitial_2026_08_11_01_00_00.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RbacHttpTokenInitial_2026_08_11_01_00_00.js","sourceRoot":"","sources":["../../../src/migrations/RbacHttpTokenInitial_2026_08_11_01_00_00.ts"],"names":[],"mappings":";;;;;;;;;AAAA,sDAAsD;AACtD,sCAAkE;AAG3D,IAAM,wCAAwC,GAA9C,MAAM,wCAAyC,SAAQ,kBAAY;IACjE,KAAK,CAAC,EAAE,CAAC,UAAqB;QACnC,MAAM,UAAU,CAAC,MAAM,EAAE,CAAC,WAAW,CAAC,oBAAoB,EAAE,CAAC,KAAK,EAAE,EAAE;YACpE,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,CAAC,aAAa,EAAE,CAAC;YAC7C,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;YACnC,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,OAAO,EAAE,CAAC;YACpC,KAAK,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;YACpC,KAAK,CAAC,MAAM,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,OAAO,EAAE,CAAC;YACrC,KAAK,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;YAC5B,KAAK,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC;YAC3D,KAAK,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC;YAC7B,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC;YAC/B,KAAK,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC;QAClE,CAAC,CAAC,CAAC;QAEH,MAAM,UAAU,CAAC,KAAK,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;QAC/G,MAAM,UAAU,CAAC,KAAK,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;QAC9G,MAAM,UAAU,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC,OAAO,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;QACxG,MAAM,UAAU,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAC,OAAO,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC;IAC/G,CAAC;IAED,gEAAgE;IACzD,KAAK,CAAC,IAAI,CAAC,WAAsB,IAAkB,CAAC;CAC5D,CAAA;;mDAvBY,wCAAwC;IADpD,IAAA,eAAS,EAAC,SAAS,CAAC;GACR,wCAAwC,CAuBpD"}

package/lib/cjs/models/AccessToken.d.ts

@@ -0,0 +1,55 @@
+import { ModelBase, SingleRelation } from '@spinajs/orm';
+import { User } from '@spinajs/rbac';
+import { DateTime } from 'luxon';
+/**
+ * Personal access token. Only the SHA-256 hash of the token is stored;
+ * the plaintext is returned once at creation and cannot be recovered.
+ */
+export declare class AccessToken extends ModelBase<AccessToken> {
+    constructor(data?: Partial<AccessToken>);
+    /**
+     * Internal row id, never leaves the process. Tokens are addressed by Uuid.
+     */
+    Id: number;
+    /**
+     * Public identifier used by the API and CLI.
+     */
+    Uuid: string;
+    /**
+     * Human readable label ("ci deploy key").
+     */
+    Name: string;
+    /**
+     * SHA-256 hex digest of the plaintext token. Hidden: even the hash is
+     * internal - leaking it invites offline correlation.
+     */
+    Token: string;
+    /**
+     * Roles allowed on this token. Effective roles at request time are the
+     * intersection of this list with the owner's current roles.
+     */
+    Roles: string[];
+    /**
+     * Absolute expiration. Null/absent = never expires.
+     *
+     * NOTE: declared optional rather than as a `DateTime | null` union - the
+     * `@DateTime()` decorator reads `design:type`, and a union is emitted as
+     * `Object`, which it rejects at decoration time. An optional property still
+     * emits `design:type = DateTime` while keeping the absence in the type.
+     */
+    ExpiresAt?: DateTime;
+    CreatedAt: DateTime;
+    /**
+     * Last successful authentication with this token. Updated throttled.
+     * Null/absent until the token is used for the first time - see the note on
+     * `ExpiresAt` for why this is optional rather than a nullable union.
+     */
+    LastUsedAt?: DateTime;
+    User: SingleRelation<User>;
+    user_id: number;
+    /**
+     * True when the token carries an expiration in the past.
+     */
+    get IsExpired(): boolean;
+}
+//# sourceMappingURL=AccessToken.d.ts.map

package/lib/cjs/models/AccessToken.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AccessToken.d.ts","sourceRoot":"","sources":["../../../src/models/AccessToken.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmE,SAAS,EAAgB,cAAc,EAAE,MAAM,cAAc,CAAC;AACxI,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAIjC;;;GAGG;AACH,qBAEa,WAAY,SAAQ,SAAS,CAAC,WAAW,CAAC;IACrD,YAAmB,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,EAG7C;IAED;;OAEG;IAGI,EAAE,EAAG,MAAM,CAAC;IAEnB;;OAEG;IACI,IAAI,EAAG,MAAM,CAAC;IAErB;;OAEG;IACI,IAAI,EAAG,MAAM,CAAC;IAErB;;;OAGG;IAEI,KAAK,EAAG,MAAM,CAAC;IAEtB;;;OAGG;IAEI,KAAK,EAAG,MAAM,EAAE,CAAC;IAExB;;;;;;;OAOG;IAEI,SAAS,CAAC,EAAE,QAAQ,CAAC;IAGrB,SAAS,EAAG,QAAQ,CAAC;IAE5B;;;;OAIG;IAEI,UAAU,CAAC,EAAE,QAAQ,CAAC;IAItB,IAAI,EAAG,cAAc,CAAC,IAAI,CAAC,CAAC;IAG5B,OAAO,EAAG,MAAM,CAAC;IAExB;;OAEG;IACH,IAAW,SAAS,IAAI,OAAO,CAE9B;CACF"}