@lemoncloud/clipbiz-backend-api 0.25.1019

package/dist/modules/auth/oauth2/oauth2-types.d.ts

@@ -0,0 +1,421 @@
+/**
+ * `oauth2-types.ts`
+ * - common type definitions for oauth2-service
+ *
+ *
+ * @author      Steve Jung <steve@lemoncloud.io>
+ * @date        2023-03-03 optimized with `lemon-core#3.2.5`
+ *
+ * @copyright (C) lemoncloud.io 2023 - All Rights Reserved.
+ */
+/**
+ * Lookup Table
+ *
+ * WARN! DO NOT EXPORT AS `$LUT`. use default export instead.
+ */
+declare const $LUT: {
+    /**
+     * SiteStereo.
+     */
+    SiteStereo: {
+        /** empty */
+        '': string;
+        /** (internal) alias type */
+        '#alias': string;
+        /** created per domain automatically (aliased by `@<domain>`) */
+        domain: string;
+        /** created by session(identity-token) automatically (alias by `@<iss>/sites/<sid>`) */
+        session: string;
+    };
+    /**
+     * HostStereo.
+     */
+    HostStereo: {
+        /** empty */
+        '': string;
+        /** (internal) alias type */
+        '#alias': string;
+    };
+    /**
+     * AccountStereo  w/ prefix
+     */
+    AccountStereo: {
+        /** empty */
+        '': string;
+        /** (internal) alias type */
+        '#alias': string;
+        /** iid (ex: identity-id) */
+        iid: string;
+        /** login (ex: admin) */
+        login: string;
+        /** phone (ex: 01012345678) */
+        phone: string;
+        /** email (ex: abc@test.com) */
+        email: string;
+        /** social (ex: google:123455) */
+        social: string;
+        /** session (see `user.alias`) */
+        session: string;
+    };
+    /**
+     * UserStereo.
+     */
+    UserStereo: {
+        /** empty */
+        '': string;
+        /** (internal) alias type */
+        '#alias': string;
+        /** created by session(identity-token) automatically (alias by `@<iss>/users/<uid>`) */
+        session: string;
+    };
+    /**
+     * GroupStereo.
+     */
+    GroupStereo: {
+        /** empty */
+        '': string;
+        /** (internal) alias type */
+        '#alias': string;
+    };
+    /**
+     * RoleStereo.
+     */
+    RoleStereo: {
+        /** empty */
+        '': string;
+        /** (internal) alias type */
+        '#alias': string;
+    };
+    /**
+     * AuthStereo.
+     */
+    AuthStereo: {
+        /** empty */
+        '': string;
+        /** (internal) alias type */
+        '#alias': string;
+        /** created by session(identity-token) automatically (alias by `@<iss>/auths/<aid>`) */
+        session: string;
+        /** login by phone */
+        phone: string;
+        /** login by email */
+        email: string;
+    };
+    /**
+     * InviteStereo.
+     */
+    InviteStereo: {
+        /** empty */
+        '': string;
+        /** (internal) alias type */
+        '#alias': string;
+    };
+};
+/**
+ * type: `AccountStereo`
+ */
+export declare type AccountStereo = keyof typeof $LUT.AccountStereo;
+/**
+ * type: `SiteStereo`
+ */
+export declare type SiteStereo = keyof typeof $LUT.SiteStereo;
+/**
+ * type: `HostStereo`
+ */
+export declare type HostStereo = keyof typeof $LUT.HostStereo;
+/**
+ * type: `UserStereo`
+ */
+export declare type UserStereo = keyof typeof $LUT.UserStereo;
+/**
+ * type: `GroupStereo`
+ */
+export declare type GroupStereo = keyof typeof $LUT.GroupStereo;
+/**
+ * type: `RoleStereo`
+ */
+export declare type RoleStereo = keyof typeof $LUT.RoleStereo;
+/**
+ * type: `AuthStereo`
+ */
+export declare type AuthStereo = keyof typeof $LUT.AuthStereo;
+/**
+ * type: `InviteStereo`
+ */
+export declare type InviteStereo = keyof typeof $LUT.InviteStereo;
+/**
+ * AWS Credentials to use
+ */
+export interface AWSCredentials {
+    /**
+     * The Access Key portion of the credentials.
+     */
+    AccessKeyId?: string;
+    /**
+     * The Secret Access Key portion of the credentials
+     */
+    SecretKey?: string;
+    /**
+     * The Session Token portion of the credentials
+     */
+    SessionToken?: string;
+    /**
+     * The date at which these credentials will expire.
+     */
+    Expiration?: string;
+}
+/**
+ * token-result from final authentication.
+ */
+export interface OAuthTokenResult {
+    /**
+     * error message if failed
+     */
+    error?: string;
+    /**
+     * auth-id via origin authorize request.
+     */
+    authId?: string;
+    /**
+     * account-id if logged successfully.
+     */
+    accountId?: string;
+    /**
+     * identity-pool-id of STS
+     */
+    identityPoolId?: string;
+    /**
+     * identity-id of authorized.
+     */
+    identityId?: string;
+    /**
+     * known as `identity-token` in format `jwt`
+     * - application에서 세션 정보(sid, uid)를 JWT형태로 저장해두기위해 이용됨
+     */
+    identityToken?: string;
+    /**
+     * access credentials to use.
+     */
+    credential?: AWSCredentials;
+}
+/**
+ * API request-param
+ * - param of `/oauth/<id>/refresh`
+ */
+export interface OAuthRefreshParam {
+    /**
+     * expired time of identity-token in second (default 1day)
+     * - if less than 1000000000, expired-time will be `current + expires`
+     * - otherwise, the timestampe of expired-time (in sec)
+     * - min: current, max: current + 1day.
+     * - use `env.MAX_JWT_EXPIRES_DAY`
+     */
+    expires?: number;
+    /**
+     * (optional) refresh-token timeout for credential in second (default 1d)
+     * - aws credential timeout is 1hour (static).
+     * - min: 0 (1s), max: 60 * 60 * 24 (24h)
+     */
+    timeout?: number;
+    /**
+     * (optional) force to issue token if role has chaned w/o 40X error.
+     */
+    force?: string | number;
+}
+/**
+ * body of `/oauth/refresh`
+ */
+export interface OAuthRefreshBody {
+    /**
+     * the current timestamp(ISO) of client
+     *
+     * ```ts
+     * const time = 1678793532758;
+     * const current = new Date(time).toISOString();
+     * expect(current).toEqual('2023-03-14T11:32:12.758Z');
+     * ```
+     */
+    current?: string;
+    /**
+     * the calclated signature string
+     *
+     * **[WORKFLOW]**
+     * 1. (pre) save identity-token in local-storage when issuing token.
+     * 2. load auth-id, account-id, identity-token, identity-id.
+     * 3. set current := new Date().toISOString()
+     * 4. set signature := Signature([current, account-id, identity-id, identity-token, user-agent].join('&'), auth-id)
+     * 5. post /refresh with current, auth-id, signature.
+     * 6. fails if time-diff is over 30min, or wrong signature.
+     *
+     * ```ts
+     * const hmac = (data: string, sig: string) => this.hmac(data, sig);
+     * const data = [current, accountId, identityId, identityToken, userAgent].join('&');
+     * const signature = hmac(hmac(hmac(data, authId), accountId), identityId);
+     * ```
+     */
+    signature?: string;
+    /**
+     * (optional) user-agent to override.
+     */
+    userAgent?: string;
+    /**
+     * target domain to get `identity-token`
+     * - only used to get new `identity-token`
+     */
+    domain?: string;
+    /**
+     * (optional) target user+site to switch (or get token)
+     * - `<uid>@<sid>`
+     */
+    target?: string;
+}
+/**
+ * type: `asAccountKeyParams`
+ */
+export interface asAccountKeyOptions {
+    /** prefix string (default undefined) */
+    prefix?: string;
+    /** delimiter between token (default '.') */
+    delim?: string;
+    /** (default true) */
+    useHash?: boolean;
+    /** (default true) */
+    useLength?: boolean;
+    /** (default true) */
+    throwable?: boolean;
+    /** errScope to override */
+    errScope?: string;
+}
+/**
+ * type: `AccountKey`
+ * - the detailed key component
+ */
+export interface AccountKey {
+    /** the final id like <prefix>.<key>.<len>  */
+    _id: string;
+    /** the hashed key */
+    key: string;
+    /** the length of alias */
+    len: string;
+    /** the prefix string */
+    prefix: string;
+    /** (optional) original alias */
+    alias?: string;
+}
+/**
+ * common jwt properties
+ */
+export interface JwtCommonPart {
+    /**
+     * expired at (sec)
+     */
+    exp?: number;
+    /**
+     * issued at (sec)
+     * = Math.floor(current_ms / 1000)
+     */
+    iat?: number;
+    /**
+     * issuer name.
+     */
+    iss?: string;
+}
+/**
+ * type: `Domain$`
+ */
+export interface Domain$ {
+    /** site-code or host-name */
+    host: string;
+    /** base domain if applicable */
+    base: string;
+}
+/**
+ * Response
+ */
+export interface OAuthAPITokenResult<S = any, U = any> extends OAuthTokenResult {
+    /** (optional) the current site-info */
+    readonly $site?: S;
+    /**
+     * (optional) the linked user-info
+     */
+    readonly $user?: U;
+}
+/**
+ * API request-body
+ * - body of `/oauth/<id>/token`
+ */
+export interface OAuthTokenBody {
+    /**
+     * code to verify token
+     */
+    code: string;
+}
+/**
+ * body of `/verify-native-token`.
+ */
+export interface VerifyNativeTokenBody {
+    /**
+     * provider of this token
+     */
+    provider?: string | 'test';
+    /**
+     * (optional) id-token
+     * - google: https://developers.google.com/identity/sign-in/web/backend-auth?hl=ko
+     */
+    idToken?: string;
+    /**
+     * (optional) identity-token for apple-id
+     * - google: https://developers.google.com/identity/sign-in/web/backend-auth?hl=ko
+     */
+    identityToken?: string;
+    /**
+     * access-token (in format of jwt)
+     */
+    accessToken?: string;
+    /**
+     * refresh-token
+     */
+    refreshToken?: string;
+    /** (optional) signature for `test` provider */
+    signature?: string;
+    /** (optional) client-id if used */
+    clientId?: string;
+    /**
+     * timestamp of client (ex: 2025-07-03T06:51:54.603Z)
+     *
+     * TODO - support `current` as string
+     * - if not provided, use `new Date().toISOString()`
+     * - used to save the time gap between server and client.
+     */
+    current?: string;
+}
+/**
+ * boolean style parameter
+ */
+export declare type BoolParam = boolean | 1 | 0 | '' | '1' | '0';
+/**
+ * param of `/login-user`
+ */
+export interface OAuthLoginUserParam {
+    /** loginId is phone */
+    phone?: BoolParam;
+    /** loginId is email */
+    email?: BoolParam;
+    /** flag to issue token */
+    token?: BoolParam;
+}
+/**
+ * body of `/login-user`
+ */
+export interface OAuthLoginUserBody {
+    /**
+     * user-id (or phone)
+     */
+    uid?: string;
+    /**
+     * password (or code)
+     */
+    pwd?: string;
+}
+/** must export $LUT as default */
+export default $LUT;