@3sixty/api-auth-entity-storage-service 0.0.0-stage → 0.20.0-next.1

package/dist/es/utils/tokenHelper.js

@@ -0,0 +1,121 @@
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+import { Coerce, Is, UnauthorizedError } from "@3sixty/core";
+import { VaultConnectorHelper } from "@3sixty/vault-models";
+import { CookieHelper, HeaderHelper, HeaderTypes, Jwt } from "@3sixty/web";
+/**
+ * Helper class for token operations.
+ */
+export class TokenHelper {
+    /**
+     * Runtime name for the class.
+     */
+    static CLASS_NAME = "TokenHelper";
+    /**
+     * Create a new token.
+     * @param vaultConnector The vault connector.
+     * @param nodeId The node identifier, embedded as the JWT issuer claim.
+     * @param signingKeyName The signing key name, embedded as the JWT key identifier.
+     * @param userIdentity The subject for the token.
+     * @param organizationIdentity The organization for the token.
+     * @param tenantId The tenant id for the token.
+     * @param ttlMinutes The time to live for the token in minutes.
+     * @param passwordVersion The user's current password version counter, embedded in the token so that a password change invalidates existing tokens.
+     * @returns The new token and its expiry date.
+     */
+    static async createToken(vaultConnector, nodeId, signingKeyName, userIdentity, organizationIdentity, tenantId, ttlMinutes, passwordVersion) {
+        const nowSeconds = Math.trunc(Date.now() / 1000);
+        const ttlSeconds = ttlMinutes * 60;
+        const vaultKeyName = `${nodeId}/${signingKeyName}`;
+        const jwt = await Jwt.encodeWithSigner({ alg: "EdDSA", kid: signingKeyName }, {
+            iss: nodeId,
+            sub: userIdentity,
+            org: organizationIdentity,
+            tid: tenantId,
+            exp: nowSeconds + ttlSeconds,
+            pver: passwordVersion
+        }, async (header, payload) => VaultConnectorHelper.jwtSigner(vaultConnector, vaultKeyName, header, payload));
+        return {
+            token: jwt,
+            expiry: (nowSeconds + ttlSeconds) * 1000
+        };
+    }
+    /**
+     * Verify the token.
+     * @param vaultConnector The vault connector.
+     * @param nodeId The node identifier, expected to match the JWT issuer claim.
+     * @param signingKeyName The signing key name, expected to match the JWT key identifier.
+     * @param token The token to verify.
+     * @param verifyUser A function to verify the user identity and organization. The password version counter embedded in the token (pver claim) is passed so callers can detect if the password has changed since the token was issued.
+     * @returns The verified details.
+     * @throws UnauthorizedError if the token is missing, invalid or expired.
+     */
+    static async verify(vaultConnector, nodeId, signingKeyName, token, verifyUser) {
+        if (!Is.stringValue(token)) {
+            throw new UnauthorizedError(TokenHelper.CLASS_NAME, "missing");
+        }
+        const vaultKeyName = `${nodeId}/${signingKeyName}`;
+        const decoded = await Jwt.verifyWithVerifier(token, async (t) => VaultConnectorHelper.jwtVerifier(vaultConnector, vaultKeyName, t));
+        // If some of the header/payload data is not properly populated then it is unauthorized.
+        if (decoded.header.kid !== signingKeyName) {
+            throw new UnauthorizedError(TokenHelper.CLASS_NAME, "headerKeyIdMismatch");
+        }
+        else if (decoded.payload.iss !== nodeId) {
+            throw new UnauthorizedError(TokenHelper.CLASS_NAME, "payloadIssuerMismatch");
+        }
+        else if (!Is.stringValue(decoded.payload.sub)) {
+            throw new UnauthorizedError(TokenHelper.CLASS_NAME, "payloadMissingSubject");
+        }
+        else if (!Is.stringValue(decoded.payload.org)) {
+            throw new UnauthorizedError(TokenHelper.CLASS_NAME, "payloadMissingOrganization");
+        }
+        else if (!Is.empty(decoded.payload?.exp) &&
+            decoded.payload.exp < Math.trunc(Date.now() / 1000)) {
+            throw new UnauthorizedError(TokenHelper.CLASS_NAME, "expired");
+        }
+        if (Is.function(verifyUser)) {
+            const tid = Coerce.string(decoded.payload.tid);
+            const userVerified = await verifyUser(decoded.payload.sub, decoded.payload.org, tid, Coerce.integer(decoded.payload.pver));
+            if (!userVerified.includes("user")) {
+                throw new UnauthorizedError(TokenHelper.CLASS_NAME, "userNotVerified");
+            }
+            else if (!userVerified.includes("organization")) {
+                throw new UnauthorizedError(TokenHelper.CLASS_NAME, "organizationNotVerified");
+            }
+            else if (Is.stringValue(tid) && !userVerified.includes("tenant")) {
+                throw new UnauthorizedError(TokenHelper.CLASS_NAME, "tenantNotVerified");
+            }
+        }
+        return {
+            header: decoded.header,
+            payload: decoded.payload
+        };
+    }
+    /**
+     * Extract the auth token from the headers, either from the authorization header or the cookie header.
+     * @param headers The headers to extract the token from.
+     * @param cookieName The name of the cookie to extract the token from.
+     * @returns The token if found.
+     */
+    static extractTokenFromHeaders(headers, cookieName) {
+        const authHeader = headers?.[HeaderTypes.Authorization];
+        const cookiesHeader = headers?.[HeaderTypes.Cookie];
+        const bearerToken = HeaderHelper.extractBearer(authHeader);
+        if (Is.stringValue(bearerToken)) {
+            return {
+                token: bearerToken,
+                location: "authorization"
+            };
+        }
+        else if (Is.notEmpty(cookiesHeader) && Is.stringValue(cookieName)) {
+            const value = CookieHelper.getCookieFromHeaders(cookiesHeader, cookieName);
+            if (Is.stringValue(value)) {
+                return {
+                    token: value,
+                    location: "cookie"
+                };
+            }
+        }
+    }
+}
+//# sourceMappingURL=tokenHelper.js.map

package/dist/es/utils/tokenHelper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokenHelper.js","sources":["../../../src/utils/tokenHelper.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { Coerce, Is, UnauthorizedError } from \"@3sixty/core\";\n\nimport { type IVaultConnector, VaultConnectorHelper } from \"@3sixty/vault-models\";\nimport {\n\tCookieHelper,\n\tHeaderHelper,\n\tHeaderTypes,\n\ttype IHttpHeaders,\n\ttype IJwtHeader,\n\ttype IJwtPayload,\n\tJwt\n} from \"@3sixty/web\";\n\n/**\n * Helper class for token operations.\n */\nexport class TokenHelper {\n\t/**\n\t * Runtime name for the class.\n\t */\n\tpublic static readonly CLASS_NAME: string = \"TokenHelper\";\n\n\t/**\n\t * Create a new token.\n\t * @param vaultConnector The vault connector.\n\t * @param nodeId The node identifier, embedded as the JWT issuer claim.\n\t * @param signingKeyName The signing key name, embedded as the JWT key identifier.\n\t * @param userIdentity The subject for the token.\n\t * @param organizationIdentity The organization for the token.\n\t * @param tenantId The tenant id for the token.\n\t * @param ttlMinutes The time to live for the token in minutes.\n\t * @param passwordVersion The user's current password version counter, embedded in the token so that a password change invalidates existing tokens.\n\t * @returns The new token and its expiry date.\n\t */\n\tpublic static async createToken(\n\t\tvaultConnector: IVaultConnector,\n\t\tnodeId: string,\n\t\tsigningKeyName: string,\n\t\tuserIdentity: string,\n\t\torganizationIdentity: string | undefined,\n\t\ttenantId: string | undefined,\n\t\tttlMinutes: number,\n\t\tpasswordVersion?: number\n\t): Promise<{\n\t\ttoken: string;\n\t\texpiry: number;\n\t}> {\n\t\tconst nowSeconds = Math.trunc(Date.now() / 1000);\n\t\tconst ttlSeconds = ttlMinutes * 60;\n\t\tconst vaultKeyName = `${nodeId}/${signingKeyName}`;\n\n\t\tconst jwt = await Jwt.encodeWithSigner(\n\t\t\t{ alg: \"EdDSA\", kid: signingKeyName },\n\t\t\t{\n\t\t\t\tiss: nodeId,\n\t\t\t\tsub: userIdentity,\n\t\t\t\torg: organizationIdentity,\n\t\t\t\ttid: tenantId,\n\t\t\t\texp: nowSeconds + ttlSeconds,\n\t\t\t\tpver: passwordVersion\n\t\t\t},\n\t\t\tasync (header, payload) =>\n\t\t\t\tVaultConnectorHelper.jwtSigner(vaultConnector, vaultKeyName, header, payload)\n\t\t);\n\n\t\treturn {\n\t\t\ttoken: jwt,\n\t\t\texpiry: (nowSeconds + ttlSeconds) * 1000\n\t\t};\n\t}\n\n\t/**\n\t * Verify the token.\n\t * @param vaultConnector The vault connector.\n\t * @param nodeId The node identifier, expected to match the JWT issuer claim.\n\t * @param signingKeyName The signing key name, expected to match the JWT key identifier.\n\t * @param token The token to verify.\n\t * @param verifyUser A function to verify the user identity and organization. The password version counter embedded in the token (pver claim) is passed so callers can detect if the password has changed since the token was issued.\n\t * @returns The verified details.\n\t * @throws UnauthorizedError if the token is missing, invalid or expired.\n\t */\n\tpublic static async verify(\n\t\tvaultConnector: IVaultConnector,\n\t\tnodeId: string,\n\t\tsigningKeyName: string,\n\t\ttoken: string | undefined,\n\t\tverifyUser?: (\n\t\t\tsub: string,\n\t\t\torg: string,\n\t\t\ttid: string | undefined,\n\t\t\tpasswordVersion: number | undefined\n\t\t) => Promise<string[]>\n\t): Promise<{\n\t\theader: IJwtHeader;\n\t\tpayload: IJwtPayload;\n\t}> {\n\t\tif (!Is.stringValue(token)) {\n\t\t\tthrow new UnauthorizedError(TokenHelper.CLASS_NAME, \"missing\");\n\t\t}\n\n\t\tconst vaultKeyName = `${nodeId}/${signingKeyName}`;\n\t\tconst decoded = await Jwt.verifyWithVerifier(token, async t =>\n\t\t\tVaultConnectorHelper.jwtVerifier(vaultConnector, vaultKeyName, t)\n\t\t);\n\n\t\t// If some of the header/payload data is not properly populated then it is unauthorized.\n\t\tif (decoded.header.kid !== signingKeyName) {\n\t\t\tthrow new UnauthorizedError(TokenHelper.CLASS_NAME, \"headerKeyIdMismatch\");\n\t\t} else if (decoded.payload.iss !== nodeId) {\n\t\t\tthrow new UnauthorizedError(TokenHelper.CLASS_NAME, \"payloadIssuerMismatch\");\n\t\t} else if (!Is.stringValue(decoded.payload.sub)) {\n\t\t\tthrow new UnauthorizedError(TokenHelper.CLASS_NAME, \"payloadMissingSubject\");\n\t\t} else if (!Is.stringValue(decoded.payload.org)) {\n\t\t\tthrow new UnauthorizedError(TokenHelper.CLASS_NAME, \"payloadMissingOrganization\");\n\t\t} else if (\n\t\t\t!Is.empty(decoded.payload?.exp) &&\n\t\t\tdecoded.payload.exp < Math.trunc(Date.now() / 1000)\n\t\t) {\n\t\t\tthrow new UnauthorizedError(TokenHelper.CLASS_NAME, \"expired\");\n\t\t}\n\n\t\tif (Is.function(verifyUser)) {\n\t\t\tconst tid = Coerce.string(decoded.payload.tid);\n\t\t\tconst userVerified = await verifyUser(\n\t\t\t\tdecoded.payload.sub,\n\t\t\t\tdecoded.payload.org,\n\t\t\t\ttid,\n\t\t\t\tCoerce.integer(decoded.payload.pver)\n\t\t\t);\n\t\t\tif (!userVerified.includes(\"user\")) {\n\t\t\t\tthrow new UnauthorizedError(TokenHelper.CLASS_NAME, \"userNotVerified\");\n\t\t\t} else if (!userVerified.includes(\"organization\")) {\n\t\t\t\tthrow new UnauthorizedError(TokenHelper.CLASS_NAME, \"organizationNotVerified\");\n\t\t\t} else if (Is.stringValue(tid) && !userVerified.includes(\"tenant\")) {\n\t\t\t\tthrow new UnauthorizedError(TokenHelper.CLASS_NAME, \"tenantNotVerified\");\n\t\t\t}\n\t\t}\n\n\t\treturn {\n\t\t\theader: decoded.header,\n\t\t\tpayload: decoded.payload\n\t\t};\n\t}\n\n\t/**\n\t * Extract the auth token from the headers, either from the authorization header or the cookie header.\n\t * @param headers The headers to extract the token from.\n\t * @param cookieName The name of the cookie to extract the token from.\n\t * @returns The token if found.\n\t */\n\tpublic static extractTokenFromHeaders(\n\t\theaders?: IHttpHeaders,\n\t\tcookieName?: string\n\t):\n\t\t| {\n\t\t\t\ttoken: string;\n\t\t\t\tlocation: \"authorization\" | \"cookie\";\n\t\t  }\n\t\t| undefined {\n\t\tconst authHeader = headers?.[HeaderTypes.Authorization];\n\t\tconst cookiesHeader = headers?.[HeaderTypes.Cookie];\n\n\t\tconst bearerToken = HeaderHelper.extractBearer(authHeader);\n\t\tif (Is.stringValue(bearerToken)) {\n\t\t\treturn {\n\t\t\t\ttoken: bearerToken,\n\t\t\t\tlocation: \"authorization\"\n\t\t\t};\n\t\t} else if (Is.notEmpty(cookiesHeader) && Is.stringValue(cookieName)) {\n\t\t\tconst value = CookieHelper.getCookieFromHeaders(cookiesHeader, cookieName);\n\t\t\tif (Is.stringValue(value)) {\n\t\t\t\treturn {\n\t\t\t\t\ttoken: value,\n\t\t\t\t\tlocation: \"cookie\"\n\t\t\t\t};\n\t\t\t}\n\t\t}\n\t}\n}\n"]}

package/dist/types/entities/authenticationUser.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Class defining the storage for user login credentials.
+ */
+export declare class AuthenticationUser {
+    /**
+     * The user e-mail address.
+     */
+    email: string;
+    /**
+     * The encrypted password for the user.
+     */
+    password: string;
+    /**
+     * The salt for the password.
+     */
+    salt: string;
+    /**
+     * The user identity.
+     */
+    identity: string;
+    /**
+     * The users organization.
+     */
+    organization: string;
+    /**
+     * The password version counter, incremented on every password change to invalidate existing tokens.
+     */
+    passwordVersion?: number;
+}

package/dist/types/entities/authenticationUserV0.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Class defining the storage for user login credentials.
+ */
+export declare class AuthenticationUserV0 {
+    /**
+     * The user e-mail address.
+     */
+    email: string;
+    /**
+     * The encrypted password for the user.
+     */
+    password: string;
+    /**
+     * The salt for the password.
+     */
+    salt: string;
+    /**
+     * The user identity.
+     */
+    identity: string;
+    /**
+     * The users organization.
+     */
+    organization: string;
+    /**
+     * The scope assigned to the user, comma separated.
+     */
+    scope: string;
+    /**
+     * The password version counter, incremented on every password change to invalidate existing tokens.
+     */
+    passwordVersion?: number;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,18 @@
+export * from "./entities/authenticationUser.js";
+export * from "./entities/authenticationUserV0.js";
+export * from "./models/IAuthHeaderProcessorConfig.js";
+export * from "./models/IAuthHeaderProcessorConstructorOptions.js";
+export * from "./models/IAuthTokenContext.js";
+export * from "./models/IEntityStorageAuthenticationAdminServiceConfig.js";
+export * from "./models/IEntityStorageAuthenticationAdminServiceConstructorOptions.js";
+export * from "./models/IEntityStorageAuthenticationServiceConfig.js";
+export * from "./models/IEntityStorageAuthenticationServiceConstructorOptions.js";
+export * from "./processors/authHeaderProcessor.js";
+export * from "./restEntryPoints.js";
+export * from "./routes/entityStorageAuthenticationAdminRoutes.js";
+export * from "./routes/entityStorageAuthenticationRoutes.js";
+export * from "./schema.js";
+export * from "./services/entityStorageAuthenticationAdminService.js";
+export * from "./services/entityStorageAuthenticationService.js";
+export * from "./utils/tokenHelper.js";
+export * from "./utils/passwordHelper.js";

package/dist/types/models/IAuthHeaderProcessorConfig.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Configuration for the authentication header processor
+ */
+export interface IAuthHeaderProcessorConfig {
+    /**
+     * The name of the key to retrieve from the vault for signing JWT.
+     * @default auth-signing
+     */
+    signingKeyName?: string;
+    /**
+     * The name of the cookie to use for the token.
+     * @default access_token
+     */
+    cookieName?: string;
+    /**
+     * Include the stack with errors.
+     */
+    includeErrorStack?: boolean;
+    /**
+     * The time in milliseconds a verified token is kept in the in-memory cache, counted from when it
+     * was verified and not extended by use, set to 0 to disable caching. A hit skips the vault
+     * signature check, the tenant lookup and the user lookup, so this is also the longest a password
+     * change, a user removal or a signing key rotation can go unnoticed. An entry never outlives the
+     * expiry claim of its own token either.
+     * @default 30000
+     */
+    tokenCacheTtlMs?: number;
+    /**
+     * The maximum number of verified tokens to hold in the in-memory cache.
+     * @default undefined (LfuCache default)
+     */
+    tokenCacheCapacity?: number;
+    /**
+     * Maximum time in milliseconds to wait for the token cache mutex during a cache population.
+     * @default undefined (LfuCache default)
+     */
+    tokenCacheMutexTimeoutMs?: number;
+}

package/dist/types/models/IAuthHeaderProcessorConstructorOptions.d.ts

@@ -0,0 +1,25 @@
+import type { IAuthHeaderProcessorConfig } from "./IAuthHeaderProcessorConfig.js";
+/**
+ * Options for the AuthHeaderProcessor constructor.
+ */
+export interface IAuthHeaderProcessorConstructorOptions {
+    /**
+     * The entity storage for users.
+     * @default authentication-user
+     */
+    userEntityStorageType?: string;
+    /**
+     * The vault for the private keys.
+     * @default vault
+     */
+    vaultConnectorType?: string;
+    /**
+     * The component to retrieve tenant information.
+     * @default tenant-admin
+     */
+    tenantAdminComponentType?: string;
+    /**
+     * The configuration for the processor.
+     */
+    config?: IAuthHeaderProcessorConfig;
+}

package/dist/types/models/IAuthTokenContext.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The context resolved from an access token, everything a request needs that does not depend on
+ * the route being called.
+ */
+export interface IAuthTokenContext {
+    /**
+     * The tenant id from the token, if it carried one.
+     */
+    tenantId?: string;
+    /**
+     * The organization id of the tenant the token belongs to.
+     */
+    tenantOrganizationId?: string;
+    /**
+     * The public origin of the tenant the token belongs to.
+     */
+    tenantPublicOrigin?: string;
+    /**
+     * The identity of the verified user.
+     */
+    userIdentity?: string;
+    /**
+     * The organization of the verified user.
+     */
+    userOrganization?: string;
+    /**
+     * The expiry of the token in milliseconds since the epoch, if it carried one.
+     */
+    expires?: number;
+}

package/dist/types/models/IEntityStorageAuthenticationAdminServiceConfig.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Configuration for the entity storage authentication admin service.
+ */
+export interface IEntityStorageAuthenticationAdminServiceConfig {
+    /**
+     * The minimum password length.
+     * @default 15
+     */
+    minPasswordLength?: number;
+    /**
+     * The maximum password length.
+     * @default 128
+     */
+    maxPasswordLength?: number;
+    /**
+     * The role that grants escalated privilege, only callers holding it can modify accounts that hold it.
+     * @default global-admin
+     */
+    escalatedPrivilegeRole?: string;
+    /**
+     * The authorization model ID used to look up roles.
+     * @default system
+     */
+    authorizationModelId?: string;
+}

package/dist/types/models/IEntityStorageAuthenticationAdminServiceConstructorOptions.d.ts

@@ -0,0 +1,25 @@
+import type { IEntityStorageAuthenticationAdminServiceConfig } from "./IEntityStorageAuthenticationAdminServiceConfig.js";
+/**
+ * Options for the EntityStorageAuthenticationAdminService constructor.
+ */
+export interface IEntityStorageAuthenticationAdminServiceConstructorOptions {
+    /**
+     * The entity storage for the users.
+     * @default authentication-user
+     */
+    userEntityStorageType?: string;
+    /**
+     * The audit component.
+     * @default authentication-audit
+     */
+    authenticationAuditServiceType?: string;
+    /**
+     * The authorization component used to guard accounts with escalated privilege.
+     * @default authorization
+     */
+    authorizationComponentType?: string;
+    /**
+     * The configuration for the authentication.
+     */
+    config?: IEntityStorageAuthenticationAdminServiceConfig;
+}

package/dist/types/models/IEntityStorageAuthenticationServiceConfig.d.ts

@@ -0,0 +1,41 @@
+import type { IAuthenticationRateActionConfig } from "@3sixty/api-auth-models";
+/**
+ * Configuration for the entity storage authentication service.
+ */
+export interface IEntityStorageAuthenticationServiceConfig {
+    /**
+     * The name of the key to retrieve from the vault for signing JWT.
+     * @default auth-signing
+     */
+    signingKeyName?: string;
+    /**
+     * The default time to live for the JWT.
+     * @default 60
+     */
+    defaultTtlMinutes?: number;
+    /**
+     * The minimum password length for new password validation.
+     * @default 15
+     */
+    minPasswordLength?: number;
+    /**
+     * The maximum password length for new password validation.
+     * @default 128
+     */
+    maxPasswordLength?: number;
+    /**
+     * Optional override for login failure rate limit.
+     * @default { maxAttempts: 5, windowMinutes: 15 }
+     */
+    loginRateLimit?: IAuthenticationRateActionConfig;
+    /**
+     * Optional override for password change rate limit.
+     * @default { maxAttempts: 5, windowMinutes: 15 }
+     */
+    passwordChangeRateLimit?: IAuthenticationRateActionConfig;
+    /**
+     * Optional override for token refresh rate limit.
+     * @default { maxAttempts: 30, windowMinutes: 60 }
+     */
+    tokenRefreshRateLimit?: IAuthenticationRateActionConfig;
+}

package/dist/types/models/IEntityStorageAuthenticationServiceConstructorOptions.d.ts

@@ -0,0 +1,35 @@
+import type { IEntityStorageAuthenticationServiceConfig } from "./IEntityStorageAuthenticationServiceConfig.js";
+/**
+ * Options for the EntityStorageAuthenticationService constructor.
+ */
+export interface IEntityStorageAuthenticationServiceConstructorOptions {
+    /**
+     * The entity storage for the users.
+     * @default authentication-user
+     */
+    userEntityStorageType?: string;
+    /**
+     * The vault for the private keys.
+     * @default vault
+     */
+    vaultConnectorType?: string;
+    /**
+     * The audit service.
+     * @default authentication-audit
+     */
+    authenticationAuditServiceType?: string;
+    /**
+     * The rate service.
+     * @default authentication-rate
+     */
+    authenticationRateServiceType?: string;
+    /**
+     * The component to retrieve tenant information.
+     * @default tenant-admin
+     */
+    tenantAdminComponentType?: string;
+    /**
+     * The configuration for the authentication.
+     */
+    config?: IEntityStorageAuthenticationServiceConfig;
+}

package/dist/types/processors/authHeaderProcessor.d.ts

@@ -0,0 +1,57 @@
+import { type IBaseRoute, type IBaseRouteProcessor, type IHttpResponse, type IHttpServerRequest } from "@3sixty/api-models";
+import { type IContextIds } from "@3sixty/context";
+import type { IAuthHeaderProcessorConstructorOptions } from "../models/IAuthHeaderProcessorConstructorOptions.js";
+/**
+ * Handle a JWT token in the authorization header or cookies and validate it to populate request context identity.
+ */
+export declare class AuthHeaderProcessor implements IBaseRouteProcessor {
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
+    /**
+     * Create a new instance of AuthHeaderProcessor.
+     * @param options Options for the processor.
+     */
+    constructor(options?: IAuthHeaderProcessorConstructorOptions);
+    /**
+     * Returns the class name of the component.
+     * @returns The class name of the component.
+     */
+    className(): string;
+    /**
+     * The service needs to be started when the application is initialized.
+     * @param nodeLoggingComponentType The node logging component type.
+     * @returns A promise that resolves when the node identity and organization ID have been cached.
+     */
+    start(nodeLoggingComponentType?: string): Promise<void>;
+    /**
+     * Stop the processor and release the token cache.
+     * @returns A promise that resolves when the processor has stopped.
+     */
+    stop(): Promise<void>;
+    /**
+     * Pre process the REST request for the specified route.
+     * @param request The incoming request.
+     * @param response The outgoing response.
+     * @param route The route to process.
+     * @param contextIds The context IDs of the request.
+     * @param processorState The state handed through the processors.
+     * @returns A promise that resolves when the JWT has been verified and the context populated, or an error response set.
+     */
+    pre(request: IHttpServerRequest, response: IHttpResponse, route: IBaseRoute | undefined, contextIds: IContextIds, processorState: {
+        [id: string]: unknown;
+    }): Promise<void>;
+    /**
+     * Post process the REST request for the specified route.
+     * @param request The incoming request.
+     * @param response The outgoing response.
+     * @param route The route to process.
+     * @param contextIds The context IDs of the request.
+     * @param processorState The state handed through the processors.
+     * @returns A promise that resolves when the Set-Cookie header has been applied to the response if required.
+     */
+    post(request: IHttpServerRequest, response: IHttpResponse, route: IBaseRoute | undefined, contextIds: IContextIds, processorState: {
+        [id: string]: unknown;
+    }): Promise<void>;
+}

package/dist/types/restEntryPoints.d.ts

@@ -0,0 +1,5 @@
+import type { IRestRouteEntryPoint } from "@3sixty/api-models";
+/**
+ * REST entry points for the authentication and authentication admin services.
+ */
+export declare const restEntryPoints: IRestRouteEntryPoint[];

package/dist/types/routes/entityStorageAuthenticationAdminRoutes.d.ts

@@ -0,0 +1,62 @@
+import type { IAdminUserCreateRequest, IAdminUserGetByIdentityRequest, IAdminUserGetRequest, IAdminUserGetResponse, IAdminUserRemoveRequest, IAdminUserUpdatePasswordRequest, IAdminUserUpdateRequest } from "@3sixty/api-auth-entity-storage-models";
+import { type ICreatedResponse, type IHttpRequestContext, type INoContentResponse, type IRestRoute, type ITag } from "@3sixty/api-models";
+/**
+ * The tag to associate with the routes.
+ */
+export declare const tagsAuthenticationAdmin: ITag[];
+/**
+ * The REST routes for authentication admin.
+ * @param baseRouteName Prefix to prepend to the paths.
+ * @param componentName The name of the component to use in the routes stored in the ComponentFactory.
+ * @returns The generated routes.
+ */
+export declare function generateRestRoutesAuthenticationAdmin(baseRouteName: string, componentName: string): IRestRoute[];
+/**
+ * Create a new user.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @param baseRouteName The base route name to use for the location header.
+ * @returns The response object with additional http response properties.
+ */
+export declare function authenticationAdminCreateUser(httpRequestContext: IHttpRequestContext, componentName: string, request: IAdminUserCreateRequest, baseRouteName: string): Promise<ICreatedResponse>;
+/**
+ * Update an existing user.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function authenticationAdminUpdateUser(httpRequestContext: IHttpRequestContext, componentName: string, request: IAdminUserUpdateRequest): Promise<INoContentResponse>;
+/**
+ * Update an existing user password.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function authenticationAdminUpdateUserPassword(httpRequestContext: IHttpRequestContext, componentName: string, request: IAdminUserUpdatePasswordRequest): Promise<INoContentResponse>;
+/**
+ * Get an existing user.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function authenticationAdminGetUser(httpRequestContext: IHttpRequestContext, componentName: string, request: IAdminUserGetRequest): Promise<IAdminUserGetResponse>;
+/**
+ * Get an existing user by identity.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function authenticationAdminGetUserByIdentity(httpRequestContext: IHttpRequestContext, componentName: string, request: IAdminUserGetByIdentityRequest): Promise<IAdminUserGetResponse>;
+/**
+ * Remove an existing user.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function authenticationAdminRemoveUser(httpRequestContext: IHttpRequestContext, componentName: string, request: IAdminUserRemoveRequest): Promise<INoContentResponse>;

package/dist/types/routes/entityStorageAuthenticationRoutes.d.ts

@@ -0,0 +1,53 @@
+import type { ILoginRequest, ILoginResponse, ILogoutRequest, IPasswordPolicyResponse, IRefreshTokenRequest, IRefreshTokenResponse, IUpdatePasswordRequest } from "@3sixty/api-auth-entity-storage-models";
+import type { IHttpRequestContext, INoContentRequest, INoContentResponse, IRestRoute, IRestRouteResponseOptions, ITag } from "@3sixty/api-models";
+/**
+ * The tag to associate with the routes.
+ */
+export declare const tagsAuthentication: ITag[];
+/**
+ * The REST routes for authentication.
+ * @param baseRouteName Prefix to prepend to the paths.
+ * @param componentName The name of the component to use in the routes stored in the ComponentFactory.
+ * @returns The generated routes.
+ */
+export declare function generateRestRoutesAuthentication(baseRouteName: string, componentName: string): IRestRoute[];
+/**
+ * Login to the server.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function authenticationLogin(httpRequestContext: IHttpRequestContext, componentName: string, request: ILoginRequest): Promise<ILoginResponse & IRestRouteResponseOptions>;
+/**
+ * Logout from the server.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function authenticationLogout(httpRequestContext: IHttpRequestContext, componentName: string, request: ILogoutRequest): Promise<INoContentResponse & IRestRouteResponseOptions>;
+/**
+ * Refresh the login token.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function authenticationRefreshToken(httpRequestContext: IHttpRequestContext, componentName: string, request: IRefreshTokenRequest): Promise<IRefreshTokenResponse & IRestRouteResponseOptions>;
+/**
+ * Update the user's password.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function authenticationUpdatePassword(httpRequestContext: IHttpRequestContext, componentName: string, request: IUpdatePasswordRequest): Promise<INoContentResponse>;
+/**
+ * Get the password policy.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function authenticationPasswordPolicy(httpRequestContext: IHttpRequestContext, componentName: string, request: INoContentRequest): Promise<IPasswordPolicyResponse & IRestRouteResponseOptions>;

package/dist/types/schema.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Initialize the schema for the authentication service.
+ */
+export declare function initSchema(): void;