alepha 0.6.7 → 0.6.9

package/security.d.ts

@@ -1 +1,651 @@
-export * from '@alepha/security';
+import * as _alepha_core from '@alepha/core';
+import { Static as Static$1, KIND, OPTIONS, Alepha } from '@alepha/core';
+import { JWSHeaderParameters, FlattenedJWSInput, CryptoKey, KeyObject, JSONWebKeySet, JWTVerifyResult, JWTPayload, JWTHeaderParameters } from 'jose';
+
+/**
+ * Represents a User Account extracted from JWT.
+ */
+interface UserAccountInfo {
+    /**
+     * ID of user account. Based on JWT.sub.
+     */
+    id: string;
+    /**
+     * Represents the roles assigned to a user.
+     */
+    roles?: string[];
+    /**
+     * User full name, if available.
+     */
+    name?: string;
+    /**
+     * Organization ID, if available.
+     */
+    organization?: string;
+}
+
+/** Symbol key applied to readonly types */
+declare const ReadonlyKind: unique symbol;
+/** Symbol key applied to optional types */
+declare const OptionalKind: unique symbol;
+/** Symbol key applied to types */
+declare const Hint: unique symbol;
+/** Symbol key applied to types */
+declare const Kind: unique symbol;
+
+type TReadonly<T extends TSchema> = T & {
+    [ReadonlyKind]: 'Readonly';
+};
+
+type StringFormatOption = 'date-time' | 'time' | 'date' | 'email' | 'idn-email' | 'hostname' | 'idn-hostname' | 'ipv4' | 'ipv6' | 'uri' | 'uri-reference' | 'iri' | 'uuid' | 'iri-reference' | 'uri-template' | 'json-pointer' | 'relative-json-pointer' | 'regex' | ({} & string);
+type StringContentEncodingOption = '7bit' | '8bit' | 'binary' | 'quoted-printable' | 'base64' | ({} & string);
+interface StringOptions extends SchemaOptions {
+    /** The maximum string length */
+    maxLength?: number;
+    /** The minimum string length */
+    minLength?: number;
+    /** A regular expression pattern this string should match */
+    pattern?: string;
+    /** A format this string should match */
+    format?: StringFormatOption;
+    /** The content encoding for this string */
+    contentEncoding?: StringContentEncodingOption;
+    /** The content media type for this string */
+    contentMediaType?: string;
+}
+interface TString extends TSchema, StringOptions {
+    [Kind]: 'String';
+    static: string;
+    type: 'string';
+}
+
+interface TBoolean extends TSchema {
+    [Kind]: 'Boolean';
+    static: boolean;
+    type: 'boolean';
+}
+
+type TOptional<T extends TSchema> = T & {
+    [OptionalKind]: 'Optional';
+};
+
+/** Creates a static type from a TypeBox type */
+type Static<Type extends TSchema, Params extends unknown[] = [], Result = (Type & {
+    params: Params;
+})['static']> = Result;
+
+type ReadonlyOptionalPropertyKeys<T extends TProperties> = {
+    [K in keyof T]: T[K] extends TReadonly<TSchema> ? (T[K] extends TOptional<T[K]> ? K : never) : never;
+}[keyof T];
+type ReadonlyPropertyKeys<T extends TProperties> = {
+    [K in keyof T]: T[K] extends TReadonly<TSchema> ? (T[K] extends TOptional<T[K]> ? never : K) : never;
+}[keyof T];
+type OptionalPropertyKeys<T extends TProperties> = {
+    [K in keyof T]: T[K] extends TOptional<TSchema> ? (T[K] extends TReadonly<T[K]> ? never : K) : never;
+}[keyof T];
+type RequiredPropertyKeys<T extends TProperties> = keyof Omit<T, ReadonlyOptionalPropertyKeys<T> | ReadonlyPropertyKeys<T> | OptionalPropertyKeys<T>>;
+type ObjectStaticProperties<T extends TProperties, R extends Record<keyof any, unknown>> = Evaluate<(Readonly<Partial<Pick<R, ReadonlyOptionalPropertyKeys<T>>>> & Readonly<Pick<R, ReadonlyPropertyKeys<T>>> & Partial<Pick<R, OptionalPropertyKeys<T>>> & Required<Pick<R, RequiredPropertyKeys<T>>>)>;
+type ObjectStatic<T extends TProperties, P extends unknown[]> = ObjectStaticProperties<T, {
+    [K in keyof T]: Static<T[K], P>;
+}>;
+type TPropertyKey = string | number;
+type TProperties = Record<TPropertyKey, TSchema>;
+type TAdditionalProperties = undefined | TSchema | boolean;
+interface ObjectOptions extends SchemaOptions {
+    /** Additional property constraints for this object */
+    additionalProperties?: TAdditionalProperties;
+    /** The minimum number of properties allowed on this object */
+    minProperties?: number;
+    /** The maximum number of properties allowed on this object */
+    maxProperties?: number;
+}
+interface TObject<T extends TProperties = TProperties> extends TSchema, ObjectOptions {
+    [Kind]: 'Object';
+    static: ObjectStatic<T, this['params']>;
+    additionalProperties?: TAdditionalProperties;
+    type: 'object';
+    properties: T;
+    required?: string[];
+}
+
+type Evaluate<T> = T extends infer O ? {
+    [K in keyof O]: O[K];
+} : never;
+type Ensure<T> = T extends infer U ? U : never;
+
+interface ArrayOptions extends SchemaOptions {
+    /** The minimum number of items in this array */
+    minItems?: number;
+    /** The maximum number of items in this array */
+    maxItems?: number;
+    /** Should this schema contain unique items */
+    uniqueItems?: boolean;
+    /** A schema for which some elements should match */
+    contains?: TSchema;
+    /** A minimum number of contains schema matches */
+    minContains?: number;
+    /** A maximum number of contains schema matches */
+    maxContains?: number;
+}
+type ArrayStatic<T extends TSchema, P extends unknown[]> = Ensure<Static<T, P>[]>;
+interface TArray<T extends TSchema = TSchema> extends TSchema, ArrayOptions {
+    [Kind]: 'Array';
+    static: ArrayStatic<T, this['params']>;
+    type: 'array';
+    items: T;
+}
+
+interface SchemaOptions {
+    $schema?: string;
+    /** Id for this schema */
+    $id?: string;
+    /** Title of this schema */
+    title?: string;
+    /** Description of this schema */
+    description?: string;
+    /** Default value for this schema */
+    default?: any;
+    /** Example values matching this schema */
+    examples?: any;
+    /** Optional annotation for readOnly */
+    readOnly?: boolean;
+    /** Optional annotation for writeOnly */
+    writeOnly?: boolean;
+    [prop: string]: any;
+}
+interface TKind {
+    [Kind]: string;
+}
+interface TSchema extends TKind, SchemaOptions {
+    [ReadonlyKind]?: string;
+    [OptionalKind]?: string;
+    [Hint]?: string;
+    params: unknown[];
+    static: unknown;
+}
+
+declare const permissionSchema: TObject<{
+    name: TString;
+    group: TOptional<TString>;
+    description: TOptional<TString>;
+    method: TOptional<TString>;
+    path: TOptional<TString>;
+    contentType: TOptional<TString>;
+}>;
+type Permission = Static$1<typeof permissionSchema>;
+
+declare const KEY$2 = "PERMISSION";
+interface PermissionDescriptorOptions {
+    /**
+     * Name of the permission. Use Property name is not provided.
+     */
+    name?: string;
+    /**
+     * Group of the permission. Use Class name is not provided.
+     */
+    group?: string;
+    /**
+     * Describe the permission.
+     */
+    description?: string;
+    /**
+     * HTTP method of the permission. When available.
+     */
+    method?: string;
+    /**
+     * URL of the permission. When available.
+     */
+    url?: string;
+}
+interface PermissionDescriptor {
+    [KIND]: typeof KEY$2;
+    [OPTIONS]: PermissionDescriptorOptions;
+    /**
+     * Get the permission object.
+     */
+    (): Permission;
+    /**
+     * Check if the user has the permission.
+     */
+    can(user: UserAccountInfo): boolean;
+}
+declare const $permission: {
+    (options?: PermissionDescriptorOptions): PermissionDescriptor;
+    [KIND]: string;
+};
+
+interface UserAccountToken extends UserAccountInfo {
+    /**
+     * Access token for the user.
+     */
+    token?: string;
+    /**
+     *
+     */
+    realm?: string;
+    /**
+     * Is user dedicated to his own resources for this scope ?
+     * Mostly, Admin is false and Customer is true.
+     */
+    ownership?: string | boolean;
+}
+
+declare const roleSchema: TObject<{
+    name: TString;
+    description: TOptional<TString>;
+    default: TOptional<TBoolean>;
+    permissions: TArray<TObject<{
+        name: TString;
+        ownership: TOptional<TBoolean>;
+    }>>;
+}>;
+type Role = Static$1<typeof roleSchema>;
+
+/**
+ * Provides utilities for working with JSON Web Tokens (JWT).
+ */
+declare class JwtProvider {
+    protected readonly log: _alepha_core.Logger;
+    protected readonly keystore: KeyLoaderHolder[];
+    /**
+     * Adds a key loader to the embedded keystore.
+     *
+     * @param name
+     * @param secretKeyOrJwks
+     */
+    setKeyLoader(name: string, secretKeyOrJwks: string | JSONWebKeySet): void;
+    /**
+     * Retrieves the payload from a JSON Web Token (JWT).
+     *
+     * @param token - The JWT to extract the payload from.
+     *
+     * @return A Promise that resolves with the payload object from the token.
+     */
+    parse(token: string): Promise<JwtParseResult>;
+    /**
+     * Creates a JWT token with the provided payload and secret key.
+     *
+     * @param payload - The payload to be encoded in the token.
+     * 	It should include the `realm_access` property which contains an array of roles.
+     * @param keyName - The name of the key to use when signing the token.
+     * @param signOptions - The options to use when signing the token.
+     *
+     * @returns The signed JWT token.
+     */
+    create(payload: ExtendedJWTPayload, keyName?: string, signOptions?: JwtSignOptions): Promise<string>;
+    /**
+     * Retrieves the options to use when signing a JWT token.
+     *
+     * @returns The JWT sign options.
+     */
+    signOptions(): JwtSignOptions;
+    /**
+     * Retrieves the first secret key from the keystore.
+     *
+     * @protected
+     */
+    protected getFirstSecretKey(): string | undefined;
+    /**
+     * Determines if the provided key is a secret key.
+     *
+     * @param key
+     * @protected
+     */
+    protected isSecretKey(key: string): boolean;
+    /**
+     * Try to find a realm name or something similar in the token.
+     *
+     * This is useful when the token is not encrypted and API has multiple realms.
+     * Instead of trying to verify the token with all keys, we can try to find the key !
+     *
+     * @param token
+     * @protected
+     */
+    protected tryToGetKeyLoaderFromToken(token: string): KeyLoaderHolder | undefined;
+}
+type KeyLoader = (protectedHeader?: JWSHeaderParameters, token?: FlattenedJWSInput) => Promise<CryptoKey | KeyObject>;
+interface KeyLoaderHolder {
+    name: string;
+    keyLoader: KeyLoader;
+    secretKey?: string;
+}
+interface JwtSignOptions {
+    issuedAt?: boolean;
+    protectedHeader?: JWTHeaderParameters;
+    expiresIn?: string | number;
+}
+interface ExtendedJWTPayload extends JWTPayload {
+    name?: string;
+    roles?: string[];
+    realm_access?: {
+        roles: string[];
+    };
+}
+interface JwtParseResult {
+    keyName: string;
+    result: JWTVerifyResult<ExtendedJWTPayload>;
+}
+
+declare const envSchema: _alepha_core.TObject<{
+    SECURITY_SECRET_KEY: TString;
+}>;
+declare module "alepha" {
+    interface Env extends Partial<Static$1<typeof envSchema>> {
+    }
+}
+declare class SecurityProvider {
+    protected readonly UNKNOWN_USER_NAME = "Unknown User";
+    protected readonly PERMISSION_REGEXP: RegExp;
+    protected readonly PERMISSION_REGEXP_WILDCARD: RegExp;
+    protected readonly log: _alepha_core.Logger;
+    protected readonly jwt: JwtProvider;
+    protected readonly env: {
+        SECURITY_SECRET_KEY: string;
+    };
+    protected readonly alepha: Alepha;
+    /**
+     * The permissions configured for the security provider.
+     */
+    protected readonly permissions: Permission[];
+    /**
+     * The realms configured for the security provider.
+     */
+    protected readonly realms: Realm[];
+    /**
+     * Create realms.
+     */
+    protected createRealms(): Realm[];
+    protected configure: _alepha_core.HookDescriptor<"configure">;
+    /**
+     * Processes all $permission descriptors.
+     */
+    protected processPermissionDescriptors(): void;
+    /**
+     * Processes all $realm descriptors.
+     */
+    protected processRealmDescriptors(): void;
+    /**
+     * Processes all $role descriptors.
+     */
+    protected processRoleDescriptors(): void;
+    protected ready: _alepha_core.HookDescriptor<"ready">;
+    /**
+     * Updates the roles for a realm then synchronizes the user account provider if available.
+     *
+     * Only available when the app is started.
+     *
+     * @param realm - The realm to update the roles for.
+     * @param roles - The roles to update.
+     */
+    updateRealm(realm: string, roles: Role[]): Promise<void>;
+    /**
+     * Adds a role to one or more realms.
+     *
+     * @param role
+     * @param realms
+     */
+    createRole(role: Role, ...realms: string[]): Role;
+    /**
+     * Adds a permission to the security provider.
+     *
+     * @param raw - The permission to add.
+     */
+    createPermission(raw: Permission | string): Permission;
+    /**
+     * Creates a user account from the provided payload.
+     *
+     * @param payload - The payload to create the user account from.
+     * @param [realm] - The realm containing the roles. Default is all.
+     *
+     * @returns The user info created from the payload.
+     */
+    createInfoFromPayload(payload: JWTPayload, realm?: string): UserAccountInfo;
+    /**
+     * Checks if the user has the specified permission.
+     *
+     * Bonus: we check also if the user has "ownership" flag.
+     *
+     * @param permissionLike - The permission to check for.
+     * @param roleEntries - The roles to check for the permission.
+     */
+    checkPermission(permissionLike: string | Permission, ...roleEntries: string[]): SecurityCheckResult;
+    /**
+     * Creates a user account from the provided payload.
+     *
+     * @param headerOrToken
+     * @param permissionLike
+     */
+    createUserFromToken(headerOrToken?: string, permissionLike?: Permission | string): Promise<UserAccountToken>;
+    /**
+     * Checks if a user has a specific role.
+     *
+     * @param roleName - The role to check for.
+     * @param permission - The permission to check for.
+     * @returns True if the user has the role, false otherwise.
+     */
+    can(role: string, permission: string | Permission): boolean;
+    /**
+     * Converts a permission object to a string.
+     *
+     * @param permission
+     */
+    permissionToString(permission: Permission | string): string;
+    getRealms(): Realm[];
+    /**
+     * Retrieves the user account from the provided user ID.
+     *
+     * @param realm
+     */
+    getRoles(realm?: string): Role[];
+    /**
+     * Returns all permissions.
+     *
+     * @param user - Filter permissions by user.
+     *
+     * @return An array containing all permissions.
+     */
+    getPermissions(user?: {
+        roles?: Array<Role | string>;
+        realm?: string;
+    }): Permission[];
+    /**
+     * Retrieves the user ID from the provided payload object.
+     *
+     * @param payload - The payload object from which to extract the user ID.
+     * @return The user ID as a string.
+     */
+    getIdFromPayload(payload: Record<string, any>): string;
+    /**
+     * Retrieves the roles from the provided payload object.
+     * @param payload - The payload object from which to extract the roles.
+     * @return An array of role strings.
+     */
+    getRolesFromPayload(payload: Record<string, any>): string[];
+    /**
+     * Returns the name from the given payload.
+     *
+     * @param payload - The payload object.
+     * @returns The name extracted from the payload, or an empty string if the payload is falsy or no name is found.
+     */
+    getNameFromPayload(payload: Record<string, any>): string;
+    getOrganizationFromPayload(payload: Record<string, any>): string | undefined;
+}
+/**
+ * A realm definition.
+ */
+interface Realm {
+    /**
+     *
+     */
+    name: string;
+    /**
+     *
+     */
+    roles: Role[];
+    /**
+     * The secret key for the realm.
+     *
+     * Can be also a JWKS URL.
+     */
+    secret?: string | JSONWebKeySet;
+    /**
+     * Attach a user provider to the realm.
+     *
+     * This is useful when you want to use a custom user provider for a specific realm.
+     */
+    userAccountProvider?: SecurityUserAccountProvider;
+}
+interface SecurityUserAccountProvider {
+    jwks: string | undefined;
+    synchronize(config: RealmConfig): Promise<void>;
+}
+interface SecurityCheckResult {
+    isAuthorized: boolean;
+    ownership: string | boolean | undefined;
+}
+interface RealmConfig {
+    roles?: Array<Role>;
+    smtp?: {
+        host?: string;
+    };
+}
+
+declare const KEY$1 = "REALM";
+interface RealmDescriptorOptions {
+    /**
+     * Define the realm name.
+     *
+     * @default key name
+     */
+    name?: string;
+    /**
+     * Describe the realm.
+     */
+    description?: string;
+    /**
+     * All roles available in the realm. Role is a string (role name) or a Role object (embedded role).
+     */
+    roles?: Array<string | Role>;
+    /**
+     * In order to verify user of the realm, a secret is required.
+     * Can be a string based secret or a JWKS URL.
+     *
+     * Note: You can skip this if you are using a user account provider with JWKS.
+     */
+    secret?: string | JSONWebKeySet;
+    /**
+     * Attach a user account provider to the realm to manage roles.
+     * For example, you can use a KeycloakUserProvider to automatically create realm roles inside Keycloak.
+     */
+    userAccountProvider?: SecurityUserAccountProvider | (() => SecurityUserAccountProvider);
+}
+interface RealmDescriptor {
+    [KIND]: typeof KEY$1;
+    [OPTIONS]: RealmDescriptorOptions;
+    /**
+     * Get all roles in the realm.
+     */
+    getRoles(): Role[];
+    /**
+     * Set all roles in the realm.
+     */
+    setRoles(roles: Role[]): Promise<void>;
+    /**
+     * Get a role by name, throws an error if not found.
+     */
+    getRoleByName(name: string): Role;
+    /**
+     * Create a token for the subject.
+     */
+    createToken(subject: string, roles?: string[]): Promise<string>;
+}
+declare const $realm: {
+    (options?: RealmDescriptorOptions): RealmDescriptor;
+    [KIND]: string;
+};
+
+declare const KEY = "ROLE";
+interface RoleDescriptorOptions {
+    /**
+     * Name of the role.
+     */
+    name?: string;
+    /**
+     * Describe the role.
+     */
+    description?: string;
+    /**
+     *
+     */
+    permissions?: Array<string | {
+        name: string;
+        ownership?: boolean;
+    }>;
+}
+interface RoleDescriptor {
+    [KIND]: typeof KEY;
+    [OPTIONS]: RoleDescriptorOptions;
+    /**
+     * Get the role object.
+     */
+    (): Role;
+}
+declare const $role: {
+    (options?: RoleDescriptorOptions): RoleDescriptor;
+    [KIND]: string;
+};
+
+/**
+ * Create a service account that can be used to authenticate with a OAUTH2 server.
+ *
+ * @param options
+ */
+declare const $serviceAccount: (options: ServiceAccountDescriptorOptions) => ServiceAccountDescriptor;
+interface ServiceAccountDescriptorOptions {
+    /**
+     * Get Token URL.
+     */
+    url: string;
+    /**
+     * Client ID.
+     */
+    clientId: string;
+    /**
+     * Client Secret.
+     */
+    clientSecret: string;
+    /**
+     * Scopes to request.
+     */
+    scope?: string;
+}
+interface ServiceAccountDescriptor {
+    options: ServiceAccountDescriptorOptions;
+    store: ServiceAccountStore;
+    token: () => Promise<string>;
+    fetch(url: string, options?: RequestInit): Promise<Response>;
+}
+interface AccessTokenResponse {
+    access_token: string;
+    expires_in: number;
+    at: number;
+}
+interface ServiceAccountStore {
+    response?: AccessTokenResponse;
+}
+
+declare class InvalidPermissionError extends Error {
+    constructor(name: string);
+}
+
+declare class SecurityError extends Error {
+    readonly status = 403;
+    readonly code = "ERR_SECURITY";
+}
+
+declare class SecurityModule {
+    protected readonly alepha: Alepha;
+    constructor();
+}
+
+export { $permission, $realm, $role, $serviceAccount, type AccessTokenResponse, type ExtendedJWTPayload, InvalidPermissionError, type JwtParseResult, JwtProvider, type JwtSignOptions, type KeyLoader, type KeyLoaderHolder, type Permission, type PermissionDescriptor, type PermissionDescriptorOptions, type Realm, type RealmConfig, type RealmDescriptor, type RealmDescriptorOptions, type Role, type RoleDescriptor, type RoleDescriptorOptions, type SecurityCheckResult, SecurityError, SecurityModule, SecurityProvider, type SecurityUserAccountProvider, type ServiceAccountDescriptor, type ServiceAccountDescriptorOptions, type ServiceAccountStore, type UserAccountInfo, type UserAccountToken, permissionSchema, roleSchema };

package/server/cookies.d.ts

@@ -1 +1,56 @@
-export * from '@alepha/server-cookies';
+import * as _alepha_core from '@alepha/core';
+import { TSchema, KIND, OPTIONS, Static } from '@alepha/core';
+import { DurationLike } from '@alepha/datetime';
+
+interface CookieDescriptorOptions<T extends TSchema> {
+    schema: T;
+    name: string;
+    path?: string;
+    ttl?: DurationLike;
+    secure?: boolean;
+    httpOnly?: boolean;
+    sameSite?: "strict" | "lax" | "none";
+    domain?: string;
+    compress?: boolean;
+    encrypt?: boolean;
+    sign?: boolean;
+}
+interface CookieDescriptor<T extends TSchema> {
+    [KIND]: "COOKIE";
+    [OPTIONS]: CookieDescriptorOptions<T>;
+    set: (cookies: Cookies, value: Static<T>) => void;
+    get: (cookies: Cookies) => Static<T> | undefined;
+    del: (cookies: Cookies) => void;
+}
+declare const $cookie: {
+    <T extends TSchema>(options: CookieDescriptorOptions<T>): CookieDescriptor<T>;
+    [KIND]: string;
+};
+interface Cookies {
+    req: Record<string, string>;
+    res: Record<string, Cookie | null>;
+}
+interface Cookie {
+    value: string;
+    path?: string;
+    maxAge?: number;
+    secure?: boolean;
+    httpOnly?: boolean;
+    sameSite?: "strict" | "lax" | "none";
+    domain?: string;
+}
+
+declare class ServerCookiesProvider {
+    readonly onRequest: _alepha_core.HookDescriptor<"server:onRequest">;
+    readonly onSend: _alepha_core.HookDescriptor<"server:onSend">;
+    fromHeader(header: string): Record<string, string>;
+    toHeader(cookies: Record<string, Cookie | null>): string[];
+}
+
+declare module "alepha/server" {
+    interface ServerRequest {
+        cookies: Cookies;
+    }
+}
+
+export { $cookie, type Cookie, type CookieDescriptor, type CookieDescriptorOptions, type Cookies, ServerCookiesProvider };