@adonisjs/auth 8.2.2 → 9.0.0-0

package/build/src/auth/define_config.d.ts

@@ -0,0 +1,30 @@
+import type { ConfigProvider } from '@adonisjs/core/types';
+import type { GuardConfigProvider, GuardFactory } from './types.js';
+import type { LucidUserProvider, DatabaseUserProvider } from './user_providers/main.js';
+import type { LucidAuthenticatable, LucidUserProviderOptions, DatabaseUserProviderOptions } from '../core/types.js';
+/**
+ * Config resolved by the "defineConfig" method
+ */
+export type ResolvedAuthConfig<KnownGuards extends Record<string, GuardFactory | GuardConfigProvider<GuardFactory>>> = {
+    default: keyof KnownGuards;
+    guards: {
+        [K in keyof KnownGuards]: KnownGuards[K] extends GuardConfigProvider<infer A> ? A : KnownGuards[K];
+    };
+};
+/**
+ * Define configuration for the auth package. The function returns
+ * a config provider that is invoked inside the auth service
+ * provider
+ */
+export declare function defineConfig<KnownGuards extends Record<string, GuardFactory | GuardConfigProvider<GuardFactory>>>(config: {
+    default: keyof KnownGuards;
+    guards: KnownGuards;
+}): ConfigProvider<ResolvedAuthConfig<KnownGuards>>;
+/**
+ * Providers helper to configure user providers for
+ * finding users for authentication
+ */
+export declare const providers: {
+    db: <RealUser extends Record<string, any>>(config: DatabaseUserProviderOptions<RealUser>) => ConfigProvider<DatabaseUserProvider<RealUser>>;
+    lucid: <RealUser extends LucidAuthenticatable>(config: LucidUserProviderOptions<RealUser>) => ConfigProvider<LucidUserProvider<RealUser>>;
+};

package/build/src/auth/define_config.js

@@ -0,0 +1,54 @@
+/*
+ * @adonisjs/auth
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+/// <reference types="@adonisjs/lucid/database_provider" />
+import { configProvider } from '@adonisjs/core';
+/**
+ * Define configuration for the auth package. The function returns
+ * a config provider that is invoked inside the auth service
+ * provider
+ */
+export function defineConfig(config) {
+    return configProvider.create(async (app) => {
+        const guardsList = Object.keys(config.guards);
+        const guards = {};
+        for (let guardName of guardsList) {
+            const guard = config.guards[guardName];
+            if (typeof guard === 'function') {
+                guards[guardName] = guard;
+            }
+            else {
+                guards[guardName] = await guard.resolver(guardName, app);
+            }
+        }
+        return {
+            default: config.default,
+            guards: guards,
+        };
+    });
+}
+/**
+ * Providers helper to configure user providers for
+ * finding users for authentication
+ */
+export const providers = {
+    db(config) {
+        return configProvider.create(async (app) => {
+            const db = await app.container.make('lucid.db');
+            const hasher = await app.container.make('hash');
+            const { DatabaseUserProvider } = await import('./user_providers/main.js');
+            return new DatabaseUserProvider(db, hasher.use(), config);
+        });
+    },
+    lucid(config) {
+        return configProvider.create(async () => {
+            const { LucidUserProvider } = await import('./user_providers/main.js');
+            return new LucidUserProvider(config);
+        });
+    },
+};

package/build/src/auth/errors.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Invalid token provided
+ */
+export declare const E_INVALID_AUTH_TOKEN: new (args?: any, options?: ErrorOptions | undefined) => import("@poppinss/utils").Exception;
+/**
+ * The user session is invalid
+ */
+export declare const E_INVALID_AUTH_SESSION: new (args?: any, options?: ErrorOptions | undefined) => import("@poppinss/utils").Exception;

package/build/src/auth/errors.js

@@ -0,0 +1,17 @@
+/*
+ * @adonisjs/auth
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+import { createError } from '@poppinss/utils';
+/**
+ * Invalid token provided
+ */
+export const E_INVALID_AUTH_TOKEN = createError('Invalid or expired token value', 'E_INVALID_AUTH_TOKEN', 401);
+/**
+ * The user session is invalid
+ */
+export const E_INVALID_AUTH_SESSION = createError('Invalid or expired authentication session', 'E_INVALID_AUTH_SESSION', 401);

package/build/src/auth/symbols.d.ts

@@ -0,0 +1,9 @@
+/**
+ * A symbol to identify the type of the real user for a given
+ * user provider
+ */
+export declare const PROVIDER_REAL_USER: unique symbol;
+/**
+ * A symbol to identify the type for the events emitted by a guard
+ */
+export declare const GUARD_KNOWN_EVENTS: unique symbol;

package/build/src/auth/symbols.js

@@ -0,0 +1,17 @@
+/*
+ * @adonisjs/lucid
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+/**
+ * A symbol to identify the type of the real user for a given
+ * user provider
+ */
+export const PROVIDER_REAL_USER = Symbol.for('PROVIDER_REAL_USER');
+/**
+ * A symbol to identify the type for the events emitted by a guard
+ */
+export const GUARD_KNOWN_EVENTS = Symbol.for('GUARD_KNOWN_EVENTS');

package/build/src/auth/types.d.ts

@@ -0,0 +1,52 @@
+import type { Emitter } from '@adonisjs/core/events';
+import type { HttpContext } from '@adonisjs/core/http';
+import type { ApplicationService, ConfigProvider } from '@adonisjs/core/types';
+import type { AuthManager } from './auth_manager.js';
+import type { GUARD_KNOWN_EVENTS } from './symbols.js';
+/**
+ * A set of properties a guard must implement.
+ */
+export interface GuardContract<User> {
+    /**
+     * Reference to the user type
+     */
+    user?: User;
+    /**
+     * Aymbol for infer the events emitted by a specific
+     * guard
+     */
+    [GUARD_KNOWN_EVENTS]: unknown;
+    /**
+     * Accept an instance of the emitter to emit events
+     */
+    withEmitter(emitter: Emitter<any>): this;
+}
+/**
+ * The authenticator guard factory method is called by the
+ * Authenticator class to create an instance of a specific
+ * guard during an HTTP request
+ */
+export type GuardFactory = (ctx: HttpContext) => GuardContract<unknown>;
+/**
+ * Authenticators are inferred inside the user application
+ * from the config file
+ */
+export interface Authenticators {
+}
+/**
+ * Infer authenticators from the auth config
+ */
+export type InferAuthenticators<Config extends ConfigProvider<unknown>> = Awaited<ReturnType<Config['resolver']>>;
+/**
+ * Auth service is a singleton instance of the AuthManager
+ * configured using the config stored within the user
+ * app.
+ */
+export interface AuthService extends AuthManager<Authenticators extends GuardFactory ? Authenticators : never> {
+}
+/**
+ * Config provider for exporting guard
+ */
+export type GuardConfigProvider<Guard extends GuardFactory> = {
+    resolver: (name: string, app: ApplicationService) => Promise<Guard>;
+};

package/build/{adonis-typings/context.js → src/auth/types.js}

@@ -1,8 +1,9 @@
 /*
  * @adonisjs/auth
  *
- * (c) Harminder Virk <virk@adonisjs.com>
+ * (c) AdonisJS
  *
  * For the full copyright and license information, please view the LICENSE
  * file that was distributed with this source code.
  */
+export {};

package/build/src/auth/user_providers/main.d.ts

@@ -0,0 +1,15 @@
+import { BaseLucidUserProvider } from '../../core/user_providers/lucid.js';
+import { BaseDatabaseUserProvider } from '../../core/user_providers/database.js';
+import type { LucidAuthenticatable, UserProviderContract } from '../../core/types.js';
+/**
+ * Using lucid models to find users for session
+ * auth
+ */
+export declare class LucidUserProvider<UserModel extends LucidAuthenticatable> extends BaseLucidUserProvider<UserModel> implements UserProviderContract<InstanceType<UserModel>> {
+}
+/**
+ * Using database query builder to find users for
+ * session auth
+ */
+export declare class DatabaseUserProvider<User extends Record<string, any>> extends BaseDatabaseUserProvider<User> implements UserProviderContract<User> {
+}

package/build/src/auth/user_providers/main.js

@@ -0,0 +1,22 @@
+/*
+ * @adonisjs/auth
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+import { BaseLucidUserProvider } from '../../core/user_providers/lucid.js';
+import { BaseDatabaseUserProvider } from '../../core/user_providers/database.js';
+/**
+ * Using lucid models to find users for session
+ * auth
+ */
+export class LucidUserProvider extends BaseLucidUserProvider {
+}
+/**
+ * Using database query builder to find users for
+ * session auth
+ */
+export class DatabaseUserProvider extends BaseDatabaseUserProvider {
+}

package/build/src/core/guard_user.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Guard user represents a user independent of the storage
+ * provider. It contains a standard set of properties
+ * used by authentication guards to interact with
+ * a user.
+ *
+ * Think of it as a bridge between a user and the authentication
+ * guard.
+ */
+export declare abstract class GuardUser<RealUser> {
+    protected realUser: RealUser;
+    constructor(realUser: RealUser);
+    /**
+     * Verifies the plain text password against the user password
+     * hash
+     */
+    abstract verifyPassword(plainTextPassword: string): Promise<boolean>;
+    /**
+     * Returns a value to uniquely identify the user.
+     */
+    abstract getId(): number | string;
+    /**
+     * Returns the original provider specific user object.
+     */
+    getOriginal(): RealUser;
+}

package/build/src/core/guard_user.js

@@ -0,0 +1,29 @@
+/*
+ * @adonisjs/auth
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+/**
+ * Guard user represents a user independent of the storage
+ * provider. It contains a standard set of properties
+ * used by authentication guards to interact with
+ * a user.
+ *
+ * Think of it as a bridge between a user and the authentication
+ * guard.
+ */
+export class GuardUser {
+    realUser;
+    constructor(realUser) {
+        this.realUser = realUser;
+    }
+    /**
+     * Returns the original provider specific user object.
+     */
+    getOriginal() {
+        return this.realUser;
+    }
+}

package/build/src/core/token.d.ts

@@ -0,0 +1,86 @@
+import type { TokenContract } from './types.js';
+/**
+ * A token represents an opaque token issued to a client
+ * to perform a specific task.
+ *
+ * The raw value of a token is only visible at the time of
+ * issuing it and one must persist hash to the database.
+ */
+export declare abstract class Token implements TokenContract {
+    /**
+     * Series is a random number stored inside the database as it is
+     */
+    series: string;
+    /**
+     * Value is a random number only available at the time of issuing
+     * the token. Afterwards, the value is undefined.
+     */
+    value: string | undefined;
+    /**
+     * Hash reference to the token hash
+     */
+    hash: string;
+    /**
+     * Token type to uniquely identify a bucket of tokens
+     */
+    abstract readonly type: string;
+    /**
+     * Arbitary meta-data associated with the token
+     */
+    metaData?: Record<string, any>;
+    /**
+     * Timestamp when the token will expire
+     */
+    expiresAt?: Date;
+    /**
+     * Date/time when the token instance was created
+     */
+    createdAt: Date;
+    /**
+     * Date/time when the token was updated
+     */
+    updatedAt: Date;
+    constructor(
+    /**
+     * Series is a random number stored inside the database as it is
+     */
+    series: string, 
+    /**
+     * Value is a random number only available at the time of issuing
+     * the token. Afterwards, the value is undefined.
+     */
+    value: string | undefined, 
+    /**
+     * Hash reference to the token hash
+     */
+    hash: string);
+    /**
+     * Define metadata for the token
+     */
+    setMetaData(metaData: Record<string, any>): this;
+    /**
+     * Verifies the value of a token against the pre-defined hash
+     */
+    verify(value: string): boolean;
+    /**
+     * Define the token expiresAt timestamp from a duration. The value
+     * value must be a number in seconds or a string expression.
+     */
+    setExpiry(duration: string | number): void;
+    /**
+     * Creates token value, series, and hash
+     */
+    static seed(size?: number): {
+        series: string;
+        value: string;
+        hash: string;
+    };
+    /**
+     * Decodes a publicly shared token and return the series
+     * and the token value from it.
+     */
+    static decode(value: string): {
+        series: string;
+        value: string;
+    };
+}

package/build/src/core/token.js

@@ -0,0 +1,112 @@
+/*
+ * @adonisjs/auth
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+import { createHash } from 'node:crypto';
+import string from '@adonisjs/core/helpers/string';
+import { base64, safeEqual } from '@adonisjs/core/helpers';
+import * as errors from '../auth/errors.js';
+/**
+ * A token represents an opaque token issued to a client
+ * to perform a specific task.
+ *
+ * The raw value of a token is only visible at the time of
+ * issuing it and one must persist hash to the database.
+ */
+export class Token {
+    series;
+    value;
+    hash;
+    /**
+     * Arbitary meta-data associated with the token
+     */
+    metaData;
+    /**
+     * Timestamp when the token will expire
+     */
+    expiresAt;
+    /**
+     * Date/time when the token instance was created
+     */
+    createdAt = new Date();
+    /**
+     * Date/time when the token was updated
+     */
+    updatedAt = new Date();
+    constructor(
+    /**
+     * Series is a random number stored inside the database as it is
+     */
+    series, 
+    /**
+     * Value is a random number only available at the time of issuing
+     * the token. Afterwards, the value is undefined.
+     */
+    value, 
+    /**
+     * Hash reference to the token hash
+     */
+    hash) {
+        this.series = series;
+        this.value = value;
+        this.hash = hash;
+    }
+    /**
+     * Define metadata for the token
+     */
+    setMetaData(metaData) {
+        this.metaData = metaData;
+        return this;
+    }
+    /**
+     * Verifies the value of a token against the pre-defined hash
+     */
+    verify(value) {
+        const newHash = createHash('sha256').update(value).digest('hex');
+        return safeEqual(this.hash, newHash);
+    }
+    /**
+     * Define the token expiresAt timestamp from a duration. The value
+     * value must be a number in seconds or a string expression.
+     */
+    setExpiry(duration) {
+        /**
+         * Defining a date object and adding seconds since the
+         * creation of the token
+         */
+        this.expiresAt = new Date();
+        this.expiresAt.setSeconds(this.createdAt.getSeconds() + string.seconds.parse(duration));
+    }
+    /**
+     * Creates token value, series, and hash
+     */
+    static seed(size = 30) {
+        const series = string.random(15);
+        const value = string.random(size);
+        const hash = createHash('sha256').update(value).digest('hex');
+        return { series, value: `${base64.urlEncode(series)}.${base64.urlEncode(value)}`, hash };
+    }
+    /**
+     * Decodes a publicly shared token and return the series
+     * and the token value from it.
+     */
+    static decode(value) {
+        const [series, ...tokenValue] = value.split('.');
+        if (!series || tokenValue.length === 0) {
+            throw new errors.E_INVALID_AUTH_TOKEN();
+        }
+        const decodedSeries = base64.urlDecode(series);
+        const decodedValue = base64.urlDecode(tokenValue.join('.'));
+        if (!decodedSeries || !decodedValue) {
+            throw new errors.E_INVALID_AUTH_TOKEN();
+        }
+        return {
+            series: decodedSeries,
+            value: decodedValue,
+        };
+    }
+}

package/build/src/core/token_providers/database.d.ts

@@ -0,0 +1,77 @@
+import type { Database } from '@adonisjs/lucid/database';
+import type { DatabaseTokenProviderOptions, TokenProviderContract } from '../types.js';
+/**
+ * The representation of a token inside the database
+ */
+type DatabaseTokenRow = {
+    series: string;
+    user_id: string | number;
+    type: string;
+    token: string;
+    created_at: Date;
+    updated_at: Date;
+    expires_at: Date | null;
+};
+/**
+ * A generic implementation to read tokens from the database
+ */
+export declare abstract class DatabaseTokenProvider<Token> implements TokenProviderContract<Token> {
+    /**
+     * Reference to the database query builder needed to
+     * query the database for tokens
+     */
+    protected db: Database;
+    /**
+     * Options accepted
+     */
+    protected options: DatabaseTokenProviderOptions;
+    constructor(
+    /**
+     * Reference to the database query builder needed to
+     * query the database for tokens
+     */
+    db: Database, 
+    /**
+     * Options accepted
+     */
+    options: DatabaseTokenProviderOptions);
+    /**
+     * Should parse token to a database token row
+     */
+    protected abstract parseToken(token: Token): DatabaseTokenRow;
+    /**
+     * Abstract method to prepare a token from the database
+     * row
+     */
+    protected abstract prepareToken(dbRow: DatabaseTokenRow): Token;
+    /**
+     * Returns an instance of the query builder
+     */
+    protected getQueryBuilder(): import("@adonisjs/lucid/types/querybuilder").DatabaseQueryBuilderContract<DatabaseTokenRow>;
+    /**
+     * Returns an instance of the query builder for insert
+     * queries
+     */
+    protected getInsertQueryBuilder(): import("@adonisjs/lucid/types/querybuilder").InsertQueryBuilderContract<any[]>;
+    /**
+     * Persists token inside the database
+     */
+    createToken(token: Token): Promise<void>;
+    /**
+     * Finds a token by series inside the database and returns an
+     * instance of it.
+     *
+     * Returns null if the token is missing or expired
+     */
+    getTokenBySeries(series: string): Promise<Token | null>;
+    /**
+     * Removes a token from the database by the
+     * series number
+     */
+    deleteTokenBySeries(series: string): Promise<void>;
+    /**
+     * Updates token hash and expiry
+     */
+    updateTokenBySeries(series: string, hash: string, expiresAt: Date): Promise<void>;
+}
+export {};