@iveri/contracts 0.6.0 → 0.7.0

package/README.md

@@ -69,8 +69,14 @@ catalogue and are already embedded in issued tokens and stored role rows.
 ### `api/identity/` → `@iveri/contracts/identity`
 
 `iveri-identity-api`'s authentication surface: `SignupBody`, `LoginBody`, `RefreshTokenBody`,
-`AcceptInvitationBody`, `AuthTokens`, `Principal`, `AuthSession`, plus `TenantStatus` and
-`MembershipStatus`.
+`AcceptInvitationBody`, `AuthTokens`, `ServiceToken`, `Principal`, `AuthSession`, plus
+`TenantStatus`, `MembershipStatus` and `PrincipalType`.
+
+It also holds **`AccessTokenPayload`** — the claims inside the JWT itself, rather than a request
+or response body. It belongs here for a stronger reason than the rest: identity is the only
+service that _issues_ a token and every other service _verifies_ one, so both sides must agree
+claim for claim. `conduit-api` kept a hand-copied duplicate until the `pt` claim had to be added
+to both at once — the drift a copy invites, arriving exactly when it is most expensive.
 
 Auth only. Identity also exposes tenant, user, membership, role and API-key routes; those have
 one consumer each and stay in the service until a second one appears.

package/dist/cjs/api/identity/access-token-payload.interface.d.ts

@@ -0,0 +1,53 @@
+import type { UserPermission } from '../../enum/user-permission.enum.js';
+import type { UUID } from '../../type/uuid.type.js';
+import type { PrincipalType } from './principal-type.enum.js';
+/**
+ * Claims carried by an access token.
+ *
+ * **`iveri-identity-api` issues these; every other service only verifies them.** The shape is
+ * therefore a contract owned by identity, and it lives here rather than in either repo because
+ * both sides have to agree byte for byte — a service whose idea of these claims has drifted
+ * does not fail loudly, it rejects every request or, worse, reads the wrong field and keeps
+ * going. `conduit-api` carried a hand-copied duplicate of this interface until the `pt` claim
+ * had to be added to both at once, which is exactly the drift the copy invited.
+ *
+ * Names are short and non-obvious (`tid`, `perms`) because this is JWT convention and because
+ * the token travels on every request — the registered claims are three characters for the same
+ * reason.
+ *
+ * **Permissions are embedded rather than resolved per request.** That is the whole point of a
+ * JWT here: any Iveri service verifies a token with the shared secret and never calls identity
+ * on the hot path. The cost is staleness — revoking a role does not invalidate access tokens
+ * already issued, so a removed permission survives up to identity's `JWT_ACCESS_TOKEN_TTL`
+ * (15 minutes by default), or `JWT_SERVICE_TOKEN_TTL` for a service token. Anything needing
+ * immediate revocation must check state at the point of use, not rely on the token.
+ */
+export interface AccessTokenPayload {
+    /**
+     * Subject — **the principal**, which is a user id or an API key id depending on {@link pt}.
+     *
+     * Read it together with `pt` or not at all. Treating it as a user id unconditionally is the
+     * one mistake this shape is arranged to prevent.
+     */
+    sub: UUID;
+    /**
+     * Which kind of principal `sub` names.
+     *
+     * Required, so adding the service-token path could not silently leave a consumer reading a
+     * machine's `sub` as a person's id.
+     */
+    pt: PrincipalType;
+    /** Tenant the token is scoped to. Becomes `RequestContext.tenantId`; never trusted from a header. */
+    tid: UUID;
+    /** Permissions resolved from the principal's roles — or from the API key's grant — at issue time. */
+    perms: UserPermission[];
+    /** Issued-at, seconds since epoch. Set by the signer. */
+    iat?: number;
+    /** Expiry, seconds since epoch. Set by the signer. */
+    exp?: number;
+    /** Issuer, verified on every decode so a token from another Iveri environment is rejected. */
+    iss?: string;
+    /** Audience, verified alongside `iss`. */
+    aud?: string;
+}
+//# sourceMappingURL=access-token-payload.interface.d.ts.map

package/dist/cjs/api/identity/access-token-payload.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"access-token-payload.interface.d.ts","sourceRoot":"","sources":["../../../../src/api/identity/access-token-payload.interface.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAE9D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,kBAAkB;IAC/B;;;;;OAKG;IACH,GAAG,EAAE,IAAI,CAAC;IAEV;;;;;OAKG;IACH,EAAE,EAAE,aAAa,CAAC;IAElB,qGAAqG;IACrG,GAAG,EAAE,IAAI,CAAC;IAEV,qGAAqG;IACrG,KAAK,EAAE,cAAc,EAAE,CAAC;IAExB,yDAAyD;IACzD,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb,sDAAsD;IACtD,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb,8FAA8F;IAC9F,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb,0CAA0C;IAC1C,GAAG,CAAC,EAAE,MAAM,CAAC;CAChB"}

package/dist/cjs/api/identity/access-token-payload.interface.js

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

package/dist/cjs/api/identity/access-token-payload.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"access-token-payload.interface.js","sourceRoot":"","sources":["../../../../src/api/identity/access-token-payload.interface.ts"],"names":[],"mappings":""}

package/dist/cjs/api/identity/auth.type.d.ts

@@ -51,6 +51,27 @@ export interface AuthTokens {
     /** Lifetime of `accessToken` in seconds, not of `refreshToken`. */
     expiresInSeconds: number;
 }
+/**
+ * Returned by `POST /auth/token` — the API-key-for-JWT exchange a service makes so that other
+ * Iveri services can authorize it **without calling identity**.
+ *
+ * **There is deliberately no refresh token.** The API key already is the long-lived credential,
+ * and it is revocable by a row. A refresh token here would be a second long-lived credential
+ * with its own independent lifetime, rotation rule and leak story, obtained from the first —
+ * so revoking the key would no longer be enough to stop the caller. A service re-exchanges
+ * instead, which costs one call per {@link expiresInSeconds}.
+ *
+ * The key travels as `x-api-key`, so this call has no request body.
+ */
+export interface ServiceToken {
+    /** Send as `Authorization: Bearer <accessToken>`. Carries `pt: 'service'`. */
+    accessToken: string;
+    /**
+     * Lifetime in seconds. Shorter than a human session's: a service re-exchanges with nobody
+     * waiting, so the revocation window is cheap to shrink.
+     */
+    expiresInSeconds: number;
+}
 /**
  * Who the caller is. Returned by `GET /auth/me` and nested inside {@link AuthSession}.
  *

package/dist/cjs/api/identity/auth.type.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.type.d.ts","sourceRoot":"","sources":["../../../../src/api/identity/auth.type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AACpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAE5D,8EAA8E;AAC9E,MAAM,WAAW,UAAU;IACvB,UAAU,EAAE,MAAM,CAAC;IAEnB,sEAAsE;IACtE,UAAU,EAAE,MAAM,CAAC;IAEnB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CACpB;AAED,0BAA0B;AAC1B,MAAM,WAAW,SAAS;IACtB;;;;;OAKG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CACpB;AAED,oDAAoD;AACpD,MAAM,WAAW,gBAAgB;IAC7B,YAAY,EAAE,MAAM,CAAC;CACxB;AAED,iGAAiG;AACjG,MAAM,WAAW,oBAAoB;IACjC,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;CACpB;AAED,+EAA+E;AAC/E,MAAM,WAAW,UAAU;IACvB,qDAAqD;IACrD,WAAW,EAAE,MAAM,CAAC;IAEpB;;;;;;;;OAQG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB,mEAAmE;IACnE,gBAAgB,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,SAAS;IACtB,qCAAqC;IACrC,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;IAEvB,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IACxB,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC5B,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAE3B,QAAQ,EAAE,IAAI,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,YAAY,CAAC;IAE3B,qCAAqC;IACrC,gBAAgB,EAAE,QAAQ,CAAC,gBAAgB,CAAC,CAAC;IAE7C,SAAS,EAAE,MAAM,EAAE,CAAC;IAEpB,gEAAgE;IAChE,WAAW,EAAE,cAAc,EAAE,CAAC;CACjC;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IACxB,SAAS,EAAE,SAAS,CAAC;IACrB,MAAM,EAAE,UAAU,CAAC;CACtB"}
+{"version":3,"file":"auth.type.d.ts","sourceRoot":"","sources":["../../../../src/api/identity/auth.type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AACpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAE5D,8EAA8E;AAC9E,MAAM,WAAW,UAAU;IACvB,UAAU,EAAE,MAAM,CAAC;IAEnB,sEAAsE;IACtE,UAAU,EAAE,MAAM,CAAC;IAEnB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CACpB;AAED,0BAA0B;AAC1B,MAAM,WAAW,SAAS;IACtB;;;;;OAKG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CACpB;AAED,oDAAoD;AACpD,MAAM,WAAW,gBAAgB;IAC7B,YAAY,EAAE,MAAM,CAAC;CACxB;AAED,iGAAiG;AACjG,MAAM,WAAW,oBAAoB;IACjC,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;CACpB;AAED,+EAA+E;AAC/E,MAAM,WAAW,UAAU;IACvB,qDAAqD;IACrD,WAAW,EAAE,MAAM,CAAC;IAEpB;;;;;;;;OAQG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB,mEAAmE;IACnE,gBAAgB,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,YAAY;IACzB,8EAA8E;IAC9E,WAAW,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,gBAAgB,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,SAAS;IACtB,qCAAqC;IACrC,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;IAEvB,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IACxB,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC5B,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAE3B,QAAQ,EAAE,IAAI,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,YAAY,CAAC;IAE3B,qCAAqC;IACrC,gBAAgB,EAAE,QAAQ,CAAC,gBAAgB,CAAC,CAAC;IAE7C,SAAS,EAAE,MAAM,EAAE,CAAC;IAEpB,gEAAgE;IAChE,WAAW,EAAE,cAAc,EAAE,CAAC;CACjC;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IACxB,SAAS,EAAE,SAAS,CAAC;IACrB,MAAM,EAAE,UAAU,CAAC;CACtB"}

package/dist/cjs/api/identity/index.d.ts

@@ -1,4 +1,6 @@
+export * from './access-token-payload.interface.js';
 export * from './auth.type.js';
 export * from './membership-status.enum.js';
+export * from './principal-type.enum.js';
 export * from './tenant-status.enum.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/cjs/api/identity/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/api/identity/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,6BAA6B,CAAC;AAC5C,cAAc,yBAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/api/identity/index.ts"],"names":[],"mappings":"AAAA,cAAc,qCAAqC,CAAC;AACpD,cAAc,gBAAgB,CAAC;AAC/B,cAAc,6BAA6B,CAAC;AAC5C,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC"}

package/dist/cjs/api/identity/index.js

@@ -14,7 +14,9 @@ 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 });
+__exportStar(require("./access-token-payload.interface.js"), exports);
 __exportStar(require("./auth.type.js"), exports);
 __exportStar(require("./membership-status.enum.js"), exports);
+__exportStar(require("./principal-type.enum.js"), exports);
 __exportStar(require("./tenant-status.enum.js"), exports);
 //# sourceMappingURL=index.js.map

package/dist/cjs/api/identity/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/api/identity/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,iDAA+B;AAC/B,8DAA4C;AAC5C,0DAAwC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/api/identity/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,sEAAoD;AACpD,iDAA+B;AAC/B,8DAA4C;AAC5C,2DAAyC;AACzC,0DAAwC"}

package/dist/cjs/api/identity/principal-type.enum.d.ts

@@ -0,0 +1,19 @@
+/**
+ * What kind of principal an access token was minted for.
+ *
+ * It exists because `sub` alone cannot answer the question. A JWT's subject is *the principal*,
+ * and identity issues tokens for two kinds of them: a person who logged in, and a service that
+ * exchanged an API key. Both put a UUID in `sub`, and the two UUIDs mean entirely different
+ * things — one names a row in `user`, the other a row in `api_key`.
+ *
+ * A consumer that reads `sub` as a user id without checking this claim attributes a machine's
+ * actions to a user who does not exist. That is why every guard branches on it, and why it is
+ * required rather than optional: `tsc` then makes the branch impossible to forget.
+ */
+export declare enum PrincipalType {
+    /** A person, authenticated by password. `sub` is their `user.id`. */
+    USER = "user",
+    /** A service, authenticated by API key. `sub` is the `api_key.id`, and there is no user. */
+    SERVICE = "service"
+}
+//# sourceMappingURL=principal-type.enum.d.ts.map

package/dist/cjs/api/identity/principal-type.enum.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"principal-type.enum.d.ts","sourceRoot":"","sources":["../../../../src/api/identity/principal-type.enum.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,oBAAY,aAAa;IACrB,qEAAqE;IACrE,IAAI,SAAS;IAEb,4FAA4F;IAC5F,OAAO,YAAY;CACtB"}

package/dist/cjs/api/identity/principal-type.enum.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PrincipalType = void 0;
+/**
+ * What kind of principal an access token was minted for.
+ *
+ * It exists because `sub` alone cannot answer the question. A JWT's subject is *the principal*,
+ * and identity issues tokens for two kinds of them: a person who logged in, and a service that
+ * exchanged an API key. Both put a UUID in `sub`, and the two UUIDs mean entirely different
+ * things — one names a row in `user`, the other a row in `api_key`.
+ *
+ * A consumer that reads `sub` as a user id without checking this claim attributes a machine's
+ * actions to a user who does not exist. That is why every guard branches on it, and why it is
+ * required rather than optional: `tsc` then makes the branch impossible to forget.
+ */
+var PrincipalType;
+(function (PrincipalType) {
+    /** A person, authenticated by password. `sub` is their `user.id`. */
+    PrincipalType["USER"] = "user";
+    /** A service, authenticated by API key. `sub` is the `api_key.id`, and there is no user. */
+    PrincipalType["SERVICE"] = "service";
+})(PrincipalType || (exports.PrincipalType = PrincipalType = {}));
+//# sourceMappingURL=principal-type.enum.js.map

package/dist/cjs/api/identity/principal-type.enum.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"principal-type.enum.js","sourceRoot":"","sources":["../../../../src/api/identity/principal-type.enum.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;GAWG;AACH,IAAY,aAMX;AAND,WAAY,aAAa;IACrB,qEAAqE;IACrE,8BAAa,CAAA;IAEb,4FAA4F;IAC5F,oCAAmB,CAAA;AACvB,CAAC,EANW,aAAa,6BAAb,aAAa,QAMxB"}

package/dist/esm/api/identity/access-token-payload.interface.d.ts

@@ -0,0 +1,53 @@
+import type { UserPermission } from '../../enum/user-permission.enum.js';
+import type { UUID } from '../../type/uuid.type.js';
+import type { PrincipalType } from './principal-type.enum.js';
+/**
+ * Claims carried by an access token.
+ *
+ * **`iveri-identity-api` issues these; every other service only verifies them.** The shape is
+ * therefore a contract owned by identity, and it lives here rather than in either repo because
+ * both sides have to agree byte for byte — a service whose idea of these claims has drifted
+ * does not fail loudly, it rejects every request or, worse, reads the wrong field and keeps
+ * going. `conduit-api` carried a hand-copied duplicate of this interface until the `pt` claim
+ * had to be added to both at once, which is exactly the drift the copy invited.
+ *
+ * Names are short and non-obvious (`tid`, `perms`) because this is JWT convention and because
+ * the token travels on every request — the registered claims are three characters for the same
+ * reason.
+ *
+ * **Permissions are embedded rather than resolved per request.** That is the whole point of a
+ * JWT here: any Iveri service verifies a token with the shared secret and never calls identity
+ * on the hot path. The cost is staleness — revoking a role does not invalidate access tokens
+ * already issued, so a removed permission survives up to identity's `JWT_ACCESS_TOKEN_TTL`
+ * (15 minutes by default), or `JWT_SERVICE_TOKEN_TTL` for a service token. Anything needing
+ * immediate revocation must check state at the point of use, not rely on the token.
+ */
+export interface AccessTokenPayload {
+    /**
+     * Subject — **the principal**, which is a user id or an API key id depending on {@link pt}.
+     *
+     * Read it together with `pt` or not at all. Treating it as a user id unconditionally is the
+     * one mistake this shape is arranged to prevent.
+     */
+    sub: UUID;
+    /**
+     * Which kind of principal `sub` names.
+     *
+     * Required, so adding the service-token path could not silently leave a consumer reading a
+     * machine's `sub` as a person's id.
+     */
+    pt: PrincipalType;
+    /** Tenant the token is scoped to. Becomes `RequestContext.tenantId`; never trusted from a header. */
+    tid: UUID;
+    /** Permissions resolved from the principal's roles — or from the API key's grant — at issue time. */
+    perms: UserPermission[];
+    /** Issued-at, seconds since epoch. Set by the signer. */
+    iat?: number;
+    /** Expiry, seconds since epoch. Set by the signer. */
+    exp?: number;
+    /** Issuer, verified on every decode so a token from another Iveri environment is rejected. */
+    iss?: string;
+    /** Audience, verified alongside `iss`. */
+    aud?: string;
+}
+//# sourceMappingURL=access-token-payload.interface.d.ts.map

package/dist/esm/api/identity/access-token-payload.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"access-token-payload.interface.d.ts","sourceRoot":"","sources":["../../../../src/api/identity/access-token-payload.interface.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAE9D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,kBAAkB;IAC/B;;;;;OAKG;IACH,GAAG,EAAE,IAAI,CAAC;IAEV;;;;;OAKG;IACH,EAAE,EAAE,aAAa,CAAC;IAElB,qGAAqG;IACrG,GAAG,EAAE,IAAI,CAAC;IAEV,qGAAqG;IACrG,KAAK,EAAE,cAAc,EAAE,CAAC;IAExB,yDAAyD;IACzD,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb,sDAAsD;IACtD,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb,8FAA8F;IAC9F,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb,0CAA0C;IAC1C,GAAG,CAAC,EAAE,MAAM,CAAC;CAChB"}

package/dist/esm/api/identity/access-token-payload.interface.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=access-token-payload.interface.js.map

package/dist/esm/api/identity/access-token-payload.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"access-token-payload.interface.js","sourceRoot":"","sources":["../../../../src/api/identity/access-token-payload.interface.ts"],"names":[],"mappings":""}

package/dist/esm/api/identity/auth.type.d.ts

@@ -51,6 +51,27 @@ export interface AuthTokens {
     /** Lifetime of `accessToken` in seconds, not of `refreshToken`. */
     expiresInSeconds: number;
 }
+/**
+ * Returned by `POST /auth/token` — the API-key-for-JWT exchange a service makes so that other
+ * Iveri services can authorize it **without calling identity**.
+ *
+ * **There is deliberately no refresh token.** The API key already is the long-lived credential,
+ * and it is revocable by a row. A refresh token here would be a second long-lived credential
+ * with its own independent lifetime, rotation rule and leak story, obtained from the first —
+ * so revoking the key would no longer be enough to stop the caller. A service re-exchanges
+ * instead, which costs one call per {@link expiresInSeconds}.
+ *
+ * The key travels as `x-api-key`, so this call has no request body.
+ */
+export interface ServiceToken {
+    /** Send as `Authorization: Bearer <accessToken>`. Carries `pt: 'service'`. */
+    accessToken: string;
+    /**
+     * Lifetime in seconds. Shorter than a human session's: a service re-exchanges with nobody
+     * waiting, so the revocation window is cheap to shrink.
+     */
+    expiresInSeconds: number;
+}
 /**
  * Who the caller is. Returned by `GET /auth/me` and nested inside {@link AuthSession}.
  *

package/dist/esm/api/identity/auth.type.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.type.d.ts","sourceRoot":"","sources":["../../../../src/api/identity/auth.type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AACpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAE5D,8EAA8E;AAC9E,MAAM,WAAW,UAAU;IACvB,UAAU,EAAE,MAAM,CAAC;IAEnB,sEAAsE;IACtE,UAAU,EAAE,MAAM,CAAC;IAEnB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CACpB;AAED,0BAA0B;AAC1B,MAAM,WAAW,SAAS;IACtB;;;;;OAKG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CACpB;AAED,oDAAoD;AACpD,MAAM,WAAW,gBAAgB;IAC7B,YAAY,EAAE,MAAM,CAAC;CACxB;AAED,iGAAiG;AACjG,MAAM,WAAW,oBAAoB;IACjC,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;CACpB;AAED,+EAA+E;AAC/E,MAAM,WAAW,UAAU;IACvB,qDAAqD;IACrD,WAAW,EAAE,MAAM,CAAC;IAEpB;;;;;;;;OAQG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB,mEAAmE;IACnE,gBAAgB,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,SAAS;IACtB,qCAAqC;IACrC,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;IAEvB,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IACxB,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC5B,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAE3B,QAAQ,EAAE,IAAI,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,YAAY,CAAC;IAE3B,qCAAqC;IACrC,gBAAgB,EAAE,QAAQ,CAAC,gBAAgB,CAAC,CAAC;IAE7C,SAAS,EAAE,MAAM,EAAE,CAAC;IAEpB,gEAAgE;IAChE,WAAW,EAAE,cAAc,EAAE,CAAC;CACjC;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IACxB,SAAS,EAAE,SAAS,CAAC;IACrB,MAAM,EAAE,UAAU,CAAC;CACtB"}
+{"version":3,"file":"auth.type.d.ts","sourceRoot":"","sources":["../../../../src/api/identity/auth.type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AACpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAE5D,8EAA8E;AAC9E,MAAM,WAAW,UAAU;IACvB,UAAU,EAAE,MAAM,CAAC;IAEnB,sEAAsE;IACtE,UAAU,EAAE,MAAM,CAAC;IAEnB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CACpB;AAED,0BAA0B;AAC1B,MAAM,WAAW,SAAS;IACtB;;;;;OAKG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CACpB;AAED,oDAAoD;AACpD,MAAM,WAAW,gBAAgB;IAC7B,YAAY,EAAE,MAAM,CAAC;CACxB;AAED,iGAAiG;AACjG,MAAM,WAAW,oBAAoB;IACjC,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;CACpB;AAED,+EAA+E;AAC/E,MAAM,WAAW,UAAU;IACvB,qDAAqD;IACrD,WAAW,EAAE,MAAM,CAAC;IAEpB;;;;;;;;OAQG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB,mEAAmE;IACnE,gBAAgB,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,YAAY;IACzB,8EAA8E;IAC9E,WAAW,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,gBAAgB,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,SAAS;IACtB,qCAAqC;IACrC,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;IAEvB,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IACxB,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC5B,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAE3B,QAAQ,EAAE,IAAI,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,YAAY,CAAC;IAE3B,qCAAqC;IACrC,gBAAgB,EAAE,QAAQ,CAAC,gBAAgB,CAAC,CAAC;IAE7C,SAAS,EAAE,MAAM,EAAE,CAAC;IAEpB,gEAAgE;IAChE,WAAW,EAAE,cAAc,EAAE,CAAC;CACjC;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IACxB,SAAS,EAAE,SAAS,CAAC;IACrB,MAAM,EAAE,UAAU,CAAC;CACtB"}

package/dist/esm/api/identity/index.d.ts

@@ -1,4 +1,6 @@
+export * from './access-token-payload.interface.js';
 export * from './auth.type.js';
 export * from './membership-status.enum.js';
+export * from './principal-type.enum.js';
 export * from './tenant-status.enum.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/esm/api/identity/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/api/identity/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,6BAA6B,CAAC;AAC5C,cAAc,yBAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/api/identity/index.ts"],"names":[],"mappings":"AAAA,cAAc,qCAAqC,CAAC;AACpD,cAAc,gBAAgB,CAAC;AAC/B,cAAc,6BAA6B,CAAC;AAC5C,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC"}

package/dist/esm/api/identity/index.js

@@ -1,4 +1,6 @@
+export * from './access-token-payload.interface.js';
 export * from './auth.type.js';
 export * from './membership-status.enum.js';
+export * from './principal-type.enum.js';
 export * from './tenant-status.enum.js';
 //# sourceMappingURL=index.js.map

package/dist/esm/api/identity/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/api/identity/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,6BAA6B,CAAC;AAC5C,cAAc,yBAAyB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/api/identity/index.ts"],"names":[],"mappings":"AAAA,cAAc,qCAAqC,CAAC;AACpD,cAAc,gBAAgB,CAAC;AAC/B,cAAc,6BAA6B,CAAC;AAC5C,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC"}

package/dist/esm/api/identity/principal-type.enum.d.ts

@@ -0,0 +1,19 @@
+/**
+ * What kind of principal an access token was minted for.
+ *
+ * It exists because `sub` alone cannot answer the question. A JWT's subject is *the principal*,
+ * and identity issues tokens for two kinds of them: a person who logged in, and a service that
+ * exchanged an API key. Both put a UUID in `sub`, and the two UUIDs mean entirely different
+ * things — one names a row in `user`, the other a row in `api_key`.
+ *
+ * A consumer that reads `sub` as a user id without checking this claim attributes a machine's
+ * actions to a user who does not exist. That is why every guard branches on it, and why it is
+ * required rather than optional: `tsc` then makes the branch impossible to forget.
+ */
+export declare enum PrincipalType {
+    /** A person, authenticated by password. `sub` is their `user.id`. */
+    USER = "user",
+    /** A service, authenticated by API key. `sub` is the `api_key.id`, and there is no user. */
+    SERVICE = "service"
+}
+//# sourceMappingURL=principal-type.enum.d.ts.map

package/dist/esm/api/identity/principal-type.enum.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"principal-type.enum.d.ts","sourceRoot":"","sources":["../../../../src/api/identity/principal-type.enum.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,oBAAY,aAAa;IACrB,qEAAqE;IACrE,IAAI,SAAS;IAEb,4FAA4F;IAC5F,OAAO,YAAY;CACtB"}

package/dist/esm/api/identity/principal-type.enum.js

@@ -0,0 +1,20 @@
+/**
+ * What kind of principal an access token was minted for.
+ *
+ * It exists because `sub` alone cannot answer the question. A JWT's subject is *the principal*,
+ * and identity issues tokens for two kinds of them: a person who logged in, and a service that
+ * exchanged an API key. Both put a UUID in `sub`, and the two UUIDs mean entirely different
+ * things — one names a row in `user`, the other a row in `api_key`.
+ *
+ * A consumer that reads `sub` as a user id without checking this claim attributes a machine's
+ * actions to a user who does not exist. That is why every guard branches on it, and why it is
+ * required rather than optional: `tsc` then makes the branch impossible to forget.
+ */
+export var PrincipalType;
+(function (PrincipalType) {
+    /** A person, authenticated by password. `sub` is their `user.id`. */
+    PrincipalType["USER"] = "user";
+    /** A service, authenticated by API key. `sub` is the `api_key.id`, and there is no user. */
+    PrincipalType["SERVICE"] = "service";
+})(PrincipalType || (PrincipalType = {}));
+//# sourceMappingURL=principal-type.enum.js.map

package/dist/esm/api/identity/principal-type.enum.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"principal-type.enum.js","sourceRoot":"","sources":["../../../../src/api/identity/principal-type.enum.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,CAAN,IAAY,aAMX;AAND,WAAY,aAAa;IACrB,qEAAqE;IACrE,8BAAa,CAAA;IAEb,4FAA4F;IAC5F,oCAAmB,CAAA;AACvB,CAAC,EANW,aAAa,KAAb,aAAa,QAMxB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iveri/contracts",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Wire contracts shared by every Iveri backend and frontend. Zero runtime dependencies.",
   "license": "MIT",
   "repository": {