@specific.dev/spectest 0.41.0 → 0.44.0

package/dist/components/github.d.ts

@@ -0,0 +1,52 @@
+import type { ProviderOptions } from "./emulate/service.js";
+export type GithubOptions = ProviderOptions;
+/**
+ * GitHub, answering at its real endpoints. Drop into
+ * `environment.services`:
+ *
+ * ```ts
+ * import { github } from "@specific.dev/spectest/components";
+ *
+ * services: {
+ *   github: github({
+ *     users: [{ email: "bob@example.com", name: "Bob Example", login: "bob" }],
+ *     client: {
+ *       clientId: "Iv1.example",
+ *       clientSecret: "ghs_example",
+ *       redirectUris: ["https://app.test/callback/github"],
+ *     },
+ *   }),
+ *   app: { …, dependsOn: ["github"] },
+ * }
+ * ```
+ *
+ * The app keeps its production configuration — it sends a browser to
+ * `https://github.com/login/oauth/authorize`, exchanges the code at
+ * `https://github.com/login/oauth/access_token`, and reads the account from
+ * `https://api.github.com/user`.
+ *
+ * The account's test id on the picker page is its **email**, even though
+ * GitHub identifies it by login — so a test reads the same whichever
+ * provider it drives.
+ */
+export declare function github(opts?: GithubOptions): {
+    image: {
+        type: "dockerfile";
+        content: string;
+    };
+    command: string;
+    files: {
+        path: string;
+        content: string;
+    }[];
+    env: {
+        SPECTEST_AUTH_CONFIG: string;
+    };
+    ports: number[];
+    readyCheck: {
+        type: "http";
+        port: number;
+        path: string;
+        timeoutSecs: number;
+    };
+};

package/dist/components/github.js

@@ -0,0 +1,90 @@
+// `github()` — GitHub, emulated inside the environment, answering at its
+// real endpoints.
+//
+// Today that is Sign in with GitHub — the authorize page, the token
+// exchange, and the profile reads every GitHub sign-in makes (`/user`,
+// `/user/emails`). The component is named for the provider rather than for
+// the feature: the backing emulator carries most of the REST API — repos,
+// issues, pull requests, checks, webhooks — and reaching it is a matter of
+// what this component chooses to expose, not of new plumbing.
+//
+// Landmine for whoever extends this: the claim is env-wide. `github.com`
+// and `api.github.com` stop reaching the internet for every container in
+// the environment, so anything else that talks to GitHub — a build step
+// that clones a repository, an unrelated API call — reaches the emulator
+// and gets a 404 outside the surface it serves.
+import { emulatorService, localPart, resolveUsers } from "./emulate/service.js";
+function spec(users, opts) {
+    const client = opts.client;
+    return {
+        name: "github",
+        module: "@emulators/github",
+        pluginExport: "githubPlugin",
+        baseUrl: "https://github.com",
+        // api.github.com cannot be avoided: every GitHub sign-in reads the
+        // profile from /user and the addresses from /user/emails.
+        hosts: ["github.com", "api.github.com"],
+        // OAuth 2.0, not OIDC — there is no id_token to re-issue and no JWKS.
+        oidc: false,
+        // GitHub identifies an account by login, not by address.
+        aliases: Object.fromEntries(users.map((u) => [u.login ?? localPart(u.email), u.email])),
+        fallbackUser: {
+            login: users[0].login ?? localPart(users[0].email),
+            id: 1,
+            scopes: ["user", "user:email"],
+        },
+        seed: {
+            users: users.map((u) => ({
+                login: u.login ?? localPart(u.email),
+                name: u.name,
+                email: u.email,
+            })),
+            // GitHub calls them oauth_apps, and its own field is `oauth_apps`.
+            ...(client
+                ? {
+                    oauth_apps: [
+                        {
+                            client_id: client.clientId,
+                            client_secret: client.clientSecret,
+                            name: "spectest",
+                            redirect_uris: client.redirectUris ?? [],
+                        },
+                    ],
+                }
+                : {}),
+        },
+    };
+}
+/**
+ * GitHub, answering at its real endpoints. Drop into
+ * `environment.services`:
+ *
+ * ```ts
+ * import { github } from "@specific.dev/spectest/components";
+ *
+ * services: {
+ *   github: github({
+ *     users: [{ email: "bob@example.com", name: "Bob Example", login: "bob" }],
+ *     client: {
+ *       clientId: "Iv1.example",
+ *       clientSecret: "ghs_example",
+ *       redirectUris: ["https://app.test/callback/github"],
+ *     },
+ *   }),
+ *   app: { …, dependsOn: ["github"] },
+ * }
+ * ```
+ *
+ * The app keeps its production configuration — it sends a browser to
+ * `https://github.com/login/oauth/authorize`, exchanges the code at
+ * `https://github.com/login/oauth/access_token`, and reads the account from
+ * `https://api.github.com/user`.
+ *
+ * The account's test id on the picker page is its **email**, even though
+ * GitHub identifies it by login — so a test reads the same whichever
+ * provider it drives.
+ */
+export function github(opts = {}) {
+    const users = resolveUsers("github", opts.users);
+    return emulatorService(spec(users, opts));
+}

package/dist/components/google.d.ts

@@ -0,0 +1,57 @@
+import type { ProviderOptions } from "./emulate/service.js";
+export type GoogleOptions = ProviderOptions;
+/**
+ * Google, answering at its real endpoints. Drop into
+ * `environment.services`:
+ *
+ * ```ts
+ * import { google } from "@specific.dev/spectest/components";
+ *
+ * services: {
+ *   // Accounts default to Alice and Bob Example; declare `users` to
+ *   // choose your own. A `client` makes the environment validate the
+ *   // app's client id, secret and callback URL.
+ *   google: google({
+ *     client: {
+ *       clientId: "1234.apps.googleusercontent.com",
+ *       clientSecret: "GOCSPX-test",
+ *       redirectUris: ["https://app.test/callback/google"],
+ *     },
+ *   }),
+ *   app: { …, dependsOn: ["google"] },
+ * }
+ * ```
+ *
+ * The app keeps its production configuration — it sends a browser to
+ * `https://accounts.google.com/o/oauth2/v2/auth`, exchanges the code at
+ * `https://oauth2.googleapis.com/token`, and verifies the id_token against
+ * `https://www.googleapis.com/oauth2/v3/certs`, exactly as it does live.
+ *
+ * A test signs in the way a user does, through the browser:
+ *
+ * ```ts
+ * await page.getByTestId("login-google").click();
+ * await page.getByTestId("spectest-user-alice@example.com").click();
+ * ```
+ */
+export declare function google(opts?: GoogleOptions): {
+    image: {
+        type: "dockerfile";
+        content: string;
+    };
+    command: string;
+    files: {
+        path: string;
+        content: string;
+    }[];
+    env: {
+        SPECTEST_AUTH_CONFIG: string;
+    };
+    ports: number[];
+    readyCheck: {
+        type: "http";
+        port: number;
+        path: string;
+        timeoutSecs: number;
+    };
+};

package/dist/components/google.js

@@ -0,0 +1,92 @@
+// `google()` — Google, emulated inside the environment, answering at its
+// real endpoints.
+//
+// Today that is Sign in with Google: OpenID Connect discovery, the account
+// picker, PKCE, the token exchange, refresh, and userinfo. The component is
+// named for the provider rather than for the feature, because the backing
+// emulator also carries Gmail, Calendar and Drive — claiming
+// `gmail.googleapis.com` and routing it here is a table entry, not a new
+// design.
+import { emulatorService, familyName, givenName, oauthClients, resolveUsers, } from "./emulate/service.js";
+function spec(users, opts) {
+    return {
+        name: "google",
+        module: "@emulators/google",
+        pluginExport: "googlePlugin",
+        baseUrl: "https://accounts.google.com",
+        hosts: [
+            "accounts.google.com",
+            "oauth2.googleapis.com",
+            "www.googleapis.com",
+            "openidconnect.googleapis.com",
+        ],
+        discovery: {
+            issuer: "https://accounts.google.com",
+            authorization_endpoint: "https://accounts.google.com/o/oauth2/v2/auth",
+            token_endpoint: "https://oauth2.googleapis.com/token",
+            userinfo_endpoint: "https://openidconnect.googleapis.com/v1/userinfo",
+            revocation_endpoint: "https://oauth2.googleapis.com/revoke",
+            jwks_uri: "https://www.googleapis.com/oauth2/v3/certs",
+        },
+        jwksPath: "^/oauth2/v3/certs$",
+        rewrites: [
+            // oauth2.googleapis.com serves these at the root; the emulator puts
+            // them under /oauth2.
+            { from: "^/token$", to: "/oauth2/token" },
+            { from: "^/revoke$", to: "/oauth2/revoke" },
+            // openidconnect.googleapis.com and the v3 alias both mean userinfo.
+            { from: "^/v1/userinfo$", to: "/oauth2/v2/userinfo" },
+            { from: "^/oauth2/v3/userinfo$", to: "/oauth2/v2/userinfo" },
+        ],
+        fallbackUser: { login: users[0].email, id: 1, scopes: ["openid", "email", "profile"] },
+        seed: {
+            users: users.map((u) => ({
+                email: u.email,
+                name: u.name,
+                given_name: givenName(u),
+                family_name: familyName(u),
+                picture: u.picture,
+                email_verified: true,
+            })),
+            ...oauthClients(opts.client),
+        },
+    };
+}
+/**
+ * Google, answering at its real endpoints. Drop into
+ * `environment.services`:
+ *
+ * ```ts
+ * import { google } from "@specific.dev/spectest/components";
+ *
+ * services: {
+ *   // Accounts default to Alice and Bob Example; declare `users` to
+ *   // choose your own. A `client` makes the environment validate the
+ *   // app's client id, secret and callback URL.
+ *   google: google({
+ *     client: {
+ *       clientId: "1234.apps.googleusercontent.com",
+ *       clientSecret: "GOCSPX-test",
+ *       redirectUris: ["https://app.test/callback/google"],
+ *     },
+ *   }),
+ *   app: { …, dependsOn: ["google"] },
+ * }
+ * ```
+ *
+ * The app keeps its production configuration — it sends a browser to
+ * `https://accounts.google.com/o/oauth2/v2/auth`, exchanges the code at
+ * `https://oauth2.googleapis.com/token`, and verifies the id_token against
+ * `https://www.googleapis.com/oauth2/v3/certs`, exactly as it does live.
+ *
+ * A test signs in the way a user does, through the browser:
+ *
+ * ```ts
+ * await page.getByTestId("login-google").click();
+ * await page.getByTestId("spectest-user-alice@example.com").click();
+ * ```
+ */
+export function google(opts = {}) {
+    const users = resolveUsers("google", opts.users);
+    return emulatorService(spec(users, opts));
+}

package/dist/components/index.d.ts

@@ -6,4 +6,10 @@ export { expo, type ExpoOptions, type ExpoHelpers, } from "./expo.js";
 export { supabase, type SupabaseOptions, type SupabaseHelpers, type SupabaseStack, } from "./supabase.js";
 export { email, type EmailOptions, type EmailHelpers, type EmailMessage, type EmailSummary, type EmailMatch, type EmailAttachment, } from "./email.js";
 export { aws, type AwsOptions, type LambdaOptions, } from "./aws.js";
+export { type ProviderOptions, type ProviderUser, type OAuthClient, } from "./emulate/service.js";
+export { google, type GoogleOptions } from "./google.js";
+export { github, type GithubOptions } from "./github.js";
+export { apple, type AppleOptions } from "./apple.js";
+export { microsoft, type MicrosoftOptions } from "./microsoft.js";
+export { okta, type OktaOptions } from "./okta.js";
 export { replayFake, type ReplayFakeOptions, type ReplayMatch, type InjectRule, type InjectMatch, type StringMatch, type SignConfig, type AwsSigV4Sign, type ReplayHelpers, type ReplaySummary, type Cassette, type CassetteInteraction, type CassetteRequest, type CassetteResponse, type CassetteState, } from "./replayFake.js";

package/dist/components/index.js

@@ -16,4 +16,9 @@ export { expo, } from "./expo.js";
 export { supabase, } from "./supabase.js";
 export { email, } from "./email.js";
 export { aws, } from "./aws.js";
+export { google } from "./google.js";
+export { github } from "./github.js";
+export { apple } from "./apple.js";
+export { microsoft } from "./microsoft.js";
+export { okta } from "./okta.js";
 export { replayFake, } from "./replayFake.js";

package/dist/components/microsoft.d.ts

@@ -0,0 +1,55 @@
+import type { ProviderOptions } from "./emulate/service.js";
+export interface MicrosoftOptions extends ProviderOptions {
+    /**
+     * Directory (tenant) the app signs in against — whatever its authority
+     * URL uses. It appears in the issuer and in every endpoint path, so a
+     * client that checks the issuer sees what it expects. Default `"common"`.
+     */
+    tenantId?: string;
+}
+/**
+ * Microsoft, answering at its real endpoints. Drop into
+ * `environment.services`:
+ *
+ * ```ts
+ * import { microsoft } from "@specific.dev/spectest/components";
+ *
+ * services: {
+ *   microsoft: microsoft({
+ *     tenantId: "11111111-2222-3333-4444-555555555555",
+ *     users: [{ email: "bob@example.com", name: "Bob Example" }],
+ *     client: {
+ *       clientId: "6f1a2b3c-…",
+ *       clientSecret: "secret",
+ *       redirectUris: ["https://app.test/callback/microsoft"],
+ *     },
+ *   }),
+ *   app: { …, dependsOn: ["microsoft"] },
+ * }
+ * ```
+ *
+ * The app keeps its production configuration — discovery at
+ * `https://login.microsoftonline.com/<tenant>/v2.0/.well-known/openid-configuration`,
+ * and the account read back from `https://graph.microsoft.com/v1.0/me`.
+ */
+export declare function microsoft(opts?: MicrosoftOptions): {
+    image: {
+        type: "dockerfile";
+        content: string;
+    };
+    command: string;
+    files: {
+        path: string;
+        content: string;
+    }[];
+    env: {
+        SPECTEST_AUTH_CONFIG: string;
+    };
+    ports: number[];
+    readyCheck: {
+        type: "http";
+        port: number;
+        path: string;
+        timeoutSecs: number;
+    };
+};

package/dist/components/microsoft.js

@@ -0,0 +1,76 @@
+// `microsoft()` — Microsoft, emulated inside the environment, answering at
+// its real endpoints.
+//
+// Today that is Sign in with Microsoft (Entra ID) plus the part of Graph an
+// app reads straight after: discovery, the account picker, the token
+// exchange, `/oidc/userinfo` and `/v1.0/me`. The component is named for the
+// provider rather than for the feature — Graph is already claimed, and
+// widening what it serves is a table entry.
+import { emulatorService, oauthClients, resolveUsers } from "./emulate/service.js";
+function spec(users, opts) {
+    const authority = `https://login.microsoftonline.com/${opts.tenantId || "common"}`;
+    return {
+        name: "microsoft",
+        module: "@emulators/microsoft",
+        pluginExport: "microsoftPlugin",
+        baseUrl: "https://login.microsoftonline.com",
+        hosts: ["login.microsoftonline.com", "graph.microsoft.com"],
+        // The emulator has no tenant, so its issuer is the bare host. A client
+        // that checks the issuer against the authority it configured would
+        // reject that; the re-issue step corrects it.
+        issuer: `${authority}/v2.0`,
+        discovery: {
+            issuer: `${authority}/v2.0`,
+            authorization_endpoint: `${authority}/oauth2/v2.0/authorize`,
+            token_endpoint: `${authority}/oauth2/v2.0/token`,
+            jwks_uri: `${authority}/discovery/v2.0/keys`,
+            end_session_endpoint: `${authority}/oauth2/v2.0/logout`,
+            userinfo_endpoint: "https://graph.microsoft.com/oidc/userinfo",
+        },
+        jwksPath: "^/discovery/v2\\.0/keys$",
+        rewrites: [
+            // Real Entra paths carry the tenant; the emulator's do not. The
+            // discovery route is the exception — it handles the tenant itself.
+            { from: "^/[^/]+/(oauth2/v2\\.0/.*)$", to: "/$1" },
+            { from: "^/[^/]+/(discovery/v2\\.0/keys)$", to: "/$1" },
+        ],
+        fallbackUser: {
+            login: users[0].email,
+            id: 1,
+            scopes: ["openid", "email", "profile", "User.Read"],
+        },
+        seed: {
+            users: users.map((u) => ({ email: u.email, name: u.name })),
+            ...oauthClients(opts.client),
+        },
+    };
+}
+/**
+ * Microsoft, answering at its real endpoints. Drop into
+ * `environment.services`:
+ *
+ * ```ts
+ * import { microsoft } from "@specific.dev/spectest/components";
+ *
+ * services: {
+ *   microsoft: microsoft({
+ *     tenantId: "11111111-2222-3333-4444-555555555555",
+ *     users: [{ email: "bob@example.com", name: "Bob Example" }],
+ *     client: {
+ *       clientId: "6f1a2b3c-…",
+ *       clientSecret: "secret",
+ *       redirectUris: ["https://app.test/callback/microsoft"],
+ *     },
+ *   }),
+ *   app: { …, dependsOn: ["microsoft"] },
+ * }
+ * ```
+ *
+ * The app keeps its production configuration — discovery at
+ * `https://login.microsoftonline.com/<tenant>/v2.0/.well-known/openid-configuration`,
+ * and the account read back from `https://graph.microsoft.com/v1.0/me`.
+ */
+export function microsoft(opts = {}) {
+    const users = resolveUsers("microsoft", opts.users);
+    return emulatorService(spec(users, opts));
+}

package/dist/components/okta.d.ts

@@ -0,0 +1,51 @@
+import type { ProviderOptions } from "./emulate/service.js";
+export interface OktaOptions extends ProviderOptions {
+    /** The org's domain, e.g. `"dev-12345.okta.com"`. */
+    domain: string;
+}
+/**
+ * Okta, answering at your org's real domain. Drop into
+ * `environment.services`:
+ *
+ * ```ts
+ * import { okta } from "@specific.dev/spectest/components";
+ *
+ * services: {
+ *   okta: okta({
+ *     domain: "dev-12345.okta.com",
+ *     users: [{ email: "alice@example.com", name: "Alice Example" }],
+ *     client: {
+ *       clientId: "0oaexample",
+ *       clientSecret: "secret",
+ *       redirectUris: ["https://app.test/callback/okta"],
+ *     },
+ *   }),
+ *   app: { …, dependsOn: ["okta"] },
+ * }
+ * ```
+ *
+ * The app keeps its production configuration — discovery at
+ * `https://dev-12345.okta.com/.well-known/openid-configuration`, and
+ * everything it names.
+ */
+export declare function okta(opts: OktaOptions): {
+    image: {
+        type: "dockerfile";
+        content: string;
+    };
+    command: string;
+    files: {
+        path: string;
+        content: string;
+    }[];
+    env: {
+        SPECTEST_AUTH_CONFIG: string;
+    };
+    ports: number[];
+    readyCheck: {
+        type: "http";
+        port: number;
+        path: string;
+        timeoutSecs: number;
+    };
+};

package/dist/components/okta.js

@@ -0,0 +1,78 @@
+// `okta()` — Okta, emulated inside the environment, answering at your org's
+// real domain.
+//
+// Today that is Okta sign-in: discovery, the account picker, the token
+// exchange, userinfo, introspection and revocation, on both the org
+// authorization server (`/oauth2/v1/…`) and a custom one
+// (`/oauth2/default/…`). The component is named for the provider rather
+// than for the feature — the backing emulator also carries the users,
+// groups and apps management API.
+//
+// Okta has no fixed hostname: every organization gets its own domain, so
+// `domain` is required where the other providers need nothing.
+import { emulatorService, familyName, givenName, oauthClients, resolveUsers, } from "./emulate/service.js";
+/** Okta's picker identifies an account by its opaque Okta id, so the id has
+ *  to be seeded rather than generated — otherwise nothing on the page can be
+ *  mapped back to an address. */
+function oktaId(email) {
+    return `u-${email.replace(/[^a-z0-9]+/gi, "-").toLowerCase()}`;
+}
+function spec(users, opts) {
+    const domain = opts.domain.toLowerCase().replace(/^https?:\/\//, "").replace(/\/.*$/, "");
+    return {
+        name: "okta",
+        module: "@emulators/okta",
+        pluginExport: "oktaPlugin",
+        baseUrl: `https://${domain}`,
+        hosts: [domain],
+        // Okta's issuer is per authorization server and the emulator already
+        // builds it from the base URL, which here is the real org domain.
+        jwksPath: "^/oauth2/(?:[^/]+/)?v1/keys$",
+        aliases: Object.fromEntries(users.map((u) => [oktaId(u.email), u.email])),
+        fallbackUser: { login: users[0].email, id: 1, scopes: ["openid", "profile", "email"] },
+        seed: {
+            users: users.map((u) => ({
+                okta_id: oktaId(u.email),
+                // An Okta login is the address, not the GitHub-style handle that
+                // `login` carries — it comes back as `preferred_username`.
+                login: u.email,
+                email: u.email,
+                first_name: givenName(u),
+                last_name: familyName(u),
+                display_name: u.name,
+            })),
+            ...oauthClients(opts.client),
+        },
+    };
+}
+/**
+ * Okta, answering at your org's real domain. Drop into
+ * `environment.services`:
+ *
+ * ```ts
+ * import { okta } from "@specific.dev/spectest/components";
+ *
+ * services: {
+ *   okta: okta({
+ *     domain: "dev-12345.okta.com",
+ *     users: [{ email: "alice@example.com", name: "Alice Example" }],
+ *     client: {
+ *       clientId: "0oaexample",
+ *       clientSecret: "secret",
+ *       redirectUris: ["https://app.test/callback/okta"],
+ *     },
+ *   }),
+ *   app: { …, dependsOn: ["okta"] },
+ * }
+ * ```
+ *
+ * The app keeps its production configuration — discovery at
+ * `https://dev-12345.okta.com/.well-known/openid-configuration`, and
+ * everything it names.
+ */
+export function okta(opts) {
+    const users = resolveUsers("okta", opts.users);
+    if (!opts.domain)
+        throw new Error("okta(): `domain` is required (e.g. \"dev-12345.okta.com\")");
+    return emulatorService(spec(users, opts));
+}