@flow-industries/id 0.26.5 → 0.27.0

package/dist/sdk/github/operations.js

@@ -0,0 +1,543 @@
+import { z } from "zod";
+/** The only host the connector ever sends a GitHub token to. */
+export const GITHUB_API_ORIGIN = "https://api.github.com";
+export const GITHUB_REQUEST_MAX_BYTES = 1_572_864;
+export const GITHUB_RESPONSE_MAX_BYTES = 8 * 1024 * 1024;
+const FILE_CONTENT_MAX_BASE64 = 1_400_000;
+const positiveInt = z.number().int().min(1).max(2_147_483_647);
+const login = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9-]{0,38}$/);
+const repoName = z
+    .string()
+    .regex(/^[A-Za-z0-9._-]{1,100}$/)
+    .refine((name) => name !== "." && name !== "..");
+const perPage = z.number().int().min(1).max(100);
+const page = z.number().int().min(1).max(1000);
+const direction = z.enum(["asc", "desc"]);
+const since = z.iso.datetime({ offset: true });
+const labelName = z.string().min(1).max(100);
+const labelFilter = labelName.regex(/^[^,]+$/);
+const markdown = z.string().max(65_536);
+const blobSha = z.string().regex(/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/);
+const gitRef = z
+    .string()
+    .min(1)
+    .max(255)
+    .regex(/^[A-Za-z0-9._/-]+$/)
+    .refine((ref) => !/^[-/]|[/.]$|\.\.|\/\/|\.lock$/.test(ref) &&
+    ref.split("/").every((part) => !part.startsWith(".")));
+const headFilter = z
+    .string()
+    .regex(/^[A-Za-z0-9][A-Za-z0-9-]{0,38}:[A-Za-z0-9._/-]{1,255}$/);
+function isSafePathSegment(segment) {
+    if (!segment || segment === "." || segment === ".." || segment.length > 255)
+        return false;
+    for (const char of segment) {
+        const code = char.codePointAt(0) ?? 0;
+        if (code < 0x20 || code === 0x7f || char === "\\")
+            return false;
+    }
+    return true;
+}
+const contentPath = z
+    .string()
+    .min(1)
+    .max(1024)
+    .refine((path) => path.split("/").every(isSafePathSegment));
+const base64 = z
+    .string()
+    .max(FILE_CONTENT_MAX_BASE64)
+    .regex(/^[A-Za-z0-9+/]*={0,2}$/)
+    .refine((value) => value.length % 4 === 0);
+const repository = { owner: login, repo: repoName };
+const paging = { per_page: perPage.optional(), page: page.optional() };
+const text = (max) => z.string().max(max);
+const url = text(2048);
+const timestamp = text(64);
+const githubAccount = z.object({
+    login: text(100),
+    id: z.number().int(),
+    avatar_url: url.optional(),
+    html_url: url.optional(),
+    type: text(32).optional(),
+});
+const viewer = githubAccount.extend({
+    name: text(512).nullish(),
+    email: text(512).nullish(),
+    bio: text(1024).nullish(),
+    company: text(512).nullish(),
+    blog: url.nullish(),
+    location: text(512).nullish(),
+    public_repos: z.number().int().optional(),
+    followers: z.number().int().optional(),
+    following: z.number().int().optional(),
+    created_at: timestamp.optional(),
+});
+const repositorySummary = z.object({
+    id: z.number().int(),
+    name: text(100),
+    full_name: text(256),
+    owner: githubAccount,
+    private: z.boolean(),
+    visibility: text(32).optional(),
+    html_url: url,
+    description: text(4096).nullish(),
+    fork: z.boolean().optional(),
+    archived: z.boolean().optional(),
+    default_branch: text(255).optional(),
+    language: text(128).nullish(),
+    stargazers_count: z.number().int().optional(),
+    forks_count: z.number().int().optional(),
+    open_issues_count: z.number().int().optional(),
+    pushed_at: timestamp.nullish(),
+    created_at: timestamp.nullish(),
+    updated_at: timestamp.nullish(),
+    permissions: z
+        .object({
+        admin: z.boolean(),
+        maintain: z.boolean().optional(),
+        push: z.boolean(),
+        triage: z.boolean().optional(),
+        pull: z.boolean(),
+    })
+        .optional(),
+});
+const label = z.object({
+    id: z.number().int().optional(),
+    name: text(256),
+    color: text(16).nullish(),
+    description: text(1024).nullish(),
+});
+const issue = z.object({
+    id: z.number().int(),
+    number: z.number().int(),
+    title: text(1024),
+    body: text(262_144).nullish(),
+    state: text(32),
+    state_reason: text(32).nullish(),
+    locked: z.boolean().optional(),
+    user: githubAccount.nullable(),
+    labels: z.array(z.union([text(256), label])).max(100),
+    assignees: z.array(githubAccount).max(100).nullish(),
+    milestone: z
+        .object({ number: z.number().int(), title: text(1024) })
+        .nullish(),
+    comments: z.number().int().optional(),
+    html_url: url,
+    created_at: timestamp,
+    updated_at: timestamp,
+    closed_at: timestamp.nullish(),
+    author_association: text(64).optional(),
+    pull_request: z
+        .object({ html_url: url.nullish(), merged_at: timestamp.nullish() })
+        .optional(),
+});
+const comment = z.object({
+    id: z.number().int(),
+    body: text(262_144).nullish(),
+    user: githubAccount.nullable(),
+    html_url: url,
+    created_at: timestamp,
+    updated_at: timestamp,
+    author_association: text(64).optional(),
+});
+const branchRef = z.object({
+    label: text(512).optional(),
+    ref: text(255),
+    sha: text(64),
+    repo: z.object({ full_name: text(256) }).nullish(),
+});
+const pullRequest = z.object({
+    id: z.number().int(),
+    number: z.number().int(),
+    title: text(1024),
+    body: text(262_144).nullish(),
+    state: text(32),
+    draft: z.boolean().optional(),
+    locked: z.boolean().optional(),
+    user: githubAccount.nullable(),
+    html_url: url,
+    created_at: timestamp,
+    updated_at: timestamp,
+    closed_at: timestamp.nullish(),
+    merged_at: timestamp.nullish(),
+    merged: z.boolean().optional(),
+    mergeable: z.boolean().nullish(),
+    head: branchRef,
+    base: branchRef,
+    labels: z.array(label).max(100).optional(),
+    assignees: z.array(githubAccount).max(100).nullish(),
+    requested_reviewers: z.array(githubAccount).max(100).nullish(),
+    comments: z.number().int().optional(),
+    commits: z.number().int().optional(),
+    additions: z.number().int().optional(),
+    deletions: z.number().int().optional(),
+    changed_files: z.number().int().optional(),
+});
+const contentEntry = z.object({
+    type: z.enum(["file", "dir", "symlink", "submodule"]),
+    name: text(255),
+    path: text(4096),
+    sha: text(64),
+    size: z.number().int(),
+    html_url: url.nullish(),
+    download_url: url.nullish(),
+});
+const content = contentEntry.extend({
+    encoding: text(32).optional(),
+    content: text(2_000_000).optional(),
+    target: text(4096).optional(),
+    submodule_git_url: url.optional(),
+});
+function define(definition) {
+    return {
+        ...definition,
+        plan(raw) {
+            const parsed = definition.input.safeParse(raw);
+            if (!parsed.success)
+                return {
+                    ok: false,
+                    fields: [
+                        ...new Set(parsed.error.issues.map((issue) => issue.path.map(String).join(".") || "(body)")),
+                    ].slice(0, 20),
+                };
+            return {
+                ok: true,
+                request: {
+                    method: definition.method,
+                    ...definition.request(parsed.data),
+                },
+                scopes: definition.scopes?.(parsed.data) ?? [],
+                repository: definition.repository ?? false,
+                paginated: definition.paginated ?? false,
+                parse: (body) => {
+                    const result = definition.response.safeParse(body);
+                    return result.success
+                        ? { ok: true, data: result.data }
+                        : { ok: false };
+                },
+            };
+        },
+    };
+}
+const optionalNumber = (value) => value === undefined ? undefined : String(value);
+const writeScopes = () => ["public_repo"];
+/**
+ * Every GitHub call the connector can make, keyed by a stable operation id.
+ * Inputs and outputs use GitHub's own field names; responses are projected to
+ * the listed fields, so anything else GitHub returns is dropped.
+ */
+export const githubOperations = {
+    "viewer.get": define({
+        method: "GET",
+        input: z.object({}).strict(),
+        response: viewer,
+        request: () => ({ segments: ["user"] }),
+    }),
+    "repos.listForViewer": define({
+        method: "GET",
+        paginated: true,
+        input: z
+            .object({
+            visibility: z.enum(["all", "public", "private"]).default("all"),
+            affiliation: z
+                .array(z.enum(["owner", "collaborator", "organization_member"]))
+                .min(1)
+                .max(3)
+                .optional(),
+            sort: z.enum(["created", "updated", "pushed", "full_name"]).optional(),
+            direction: direction.optional(),
+            ...paging,
+        })
+            .strict(),
+        response: z.array(repositorySummary).max(100),
+        scopes: (input) => (input.visibility === "public" ? [] : ["repo"]),
+        request: (input) => ({
+            segments: ["user", "repos"],
+            query: {
+                visibility: input.visibility,
+                affiliation: input.affiliation
+                    ? [...new Set(input.affiliation)].join(",")
+                    : undefined,
+                sort: input.sort,
+                direction: input.direction,
+                per_page: optionalNumber(input.per_page),
+                page: optionalNumber(input.page),
+            },
+        }),
+    }),
+    "repos.get": define({
+        method: "GET",
+        repository: true,
+        input: z.object(repository).strict(),
+        response: repositorySummary,
+        request: (input) => ({ segments: ["repos", input.owner, input.repo] }),
+    }),
+    "issues.list": define({
+        method: "GET",
+        repository: true,
+        paginated: true,
+        input: z
+            .object({
+            ...repository,
+            state: z.enum(["open", "closed", "all"]).optional(),
+            labels: z.array(labelFilter).min(1).max(20).optional(),
+            sort: z.enum(["created", "updated", "comments"]).optional(),
+            direction: direction.optional(),
+            since: since.optional(),
+            ...paging,
+        })
+            .strict(),
+        response: z.array(issue).max(100),
+        request: (input) => ({
+            segments: ["repos", input.owner, input.repo, "issues"],
+            query: {
+                state: input.state,
+                labels: input.labels?.join(","),
+                sort: input.sort,
+                direction: input.direction,
+                since: input.since,
+                per_page: optionalNumber(input.per_page),
+                page: optionalNumber(input.page),
+            },
+        }),
+    }),
+    "issues.get": define({
+        method: "GET",
+        repository: true,
+        input: z.object({ ...repository, issue_number: positiveInt }).strict(),
+        response: issue,
+        request: (input) => ({
+            segments: [
+                "repos",
+                input.owner,
+                input.repo,
+                "issues",
+                String(input.issue_number),
+            ],
+        }),
+    }),
+    "issues.create": define({
+        method: "POST",
+        repository: true,
+        input: z
+            .object({
+            ...repository,
+            title: z.string().min(1).max(256),
+            body: markdown.optional(),
+            labels: z.array(labelName).max(100).optional(),
+            assignees: z.array(login).max(10).optional(),
+            milestone: positiveInt.nullable().optional(),
+        })
+            .strict(),
+        response: issue,
+        scopes: writeScopes,
+        request: ({ owner, repo, ...body }) => ({
+            segments: ["repos", owner, repo, "issues"],
+            body,
+        }),
+    }),
+    "issues.update": define({
+        method: "PATCH",
+        repository: true,
+        input: z
+            .object({
+            ...repository,
+            issue_number: positiveInt,
+            title: z.string().min(1).max(256).optional(),
+            body: markdown.nullable().optional(),
+            state: z.enum(["open", "closed"]).optional(),
+            state_reason: z
+                .enum(["completed", "not_planned", "reopened"])
+                .nullable()
+                .optional(),
+            labels: z.array(labelName).max(100).optional(),
+            assignees: z.array(login).max(10).optional(),
+            milestone: positiveInt.nullable().optional(),
+        })
+            .strict()
+            .refine((input) => [
+            input.title,
+            input.body,
+            input.state,
+            input.state_reason,
+            input.labels,
+            input.assignees,
+            input.milestone,
+        ].some((value) => value !== undefined), { message: "Nothing to update" }),
+        response: issue,
+        scopes: writeScopes,
+        request: ({ owner, repo, issue_number, ...body }) => ({
+            segments: ["repos", owner, repo, "issues", String(issue_number)],
+            body,
+        }),
+    }),
+    "issues.listComments": define({
+        method: "GET",
+        repository: true,
+        paginated: true,
+        input: z
+            .object({
+            ...repository,
+            issue_number: positiveInt,
+            since: since.optional(),
+            ...paging,
+        })
+            .strict(),
+        response: z.array(comment).max(100),
+        request: (input) => ({
+            segments: [
+                "repos",
+                input.owner,
+                input.repo,
+                "issues",
+                String(input.issue_number),
+                "comments",
+            ],
+            query: {
+                since: input.since,
+                per_page: optionalNumber(input.per_page),
+                page: optionalNumber(input.page),
+            },
+        }),
+    }),
+    "issues.createComment": define({
+        method: "POST",
+        repository: true,
+        input: z
+            .object({
+            ...repository,
+            issue_number: positiveInt,
+            body: markdown.min(1),
+        })
+            .strict(),
+        response: comment,
+        scopes: writeScopes,
+        request: ({ owner, repo, issue_number, body }) => ({
+            segments: [
+                "repos",
+                owner,
+                repo,
+                "issues",
+                String(issue_number),
+                "comments",
+            ],
+            body: { body },
+        }),
+    }),
+    "pulls.list": define({
+        method: "GET",
+        repository: true,
+        paginated: true,
+        input: z
+            .object({
+            ...repository,
+            state: z.enum(["open", "closed", "all"]).optional(),
+            head: headFilter.optional(),
+            base: gitRef.optional(),
+            sort: z
+                .enum(["created", "updated", "popularity", "long-running"])
+                .optional(),
+            direction: direction.optional(),
+            ...paging,
+        })
+            .strict(),
+        response: z.array(pullRequest).max(100),
+        request: (input) => ({
+            segments: ["repos", input.owner, input.repo, "pulls"],
+            query: {
+                state: input.state,
+                head: input.head,
+                base: input.base,
+                sort: input.sort,
+                direction: input.direction,
+                per_page: optionalNumber(input.per_page),
+                page: optionalNumber(input.page),
+            },
+        }),
+    }),
+    "pulls.get": define({
+        method: "GET",
+        repository: true,
+        input: z.object({ ...repository, pull_number: positiveInt }).strict(),
+        response: pullRequest,
+        request: (input) => ({
+            segments: [
+                "repos",
+                input.owner,
+                input.repo,
+                "pulls",
+                String(input.pull_number),
+            ],
+        }),
+    }),
+    "repos.getContent": define({
+        method: "GET",
+        repository: true,
+        input: z
+            .object({
+            ...repository,
+            path: contentPath.optional(),
+            ref: gitRef.optional(),
+        })
+            .strict(),
+        response: z.union([z.array(contentEntry).max(1000), content]),
+        request: (input) => ({
+            segments: [
+                "repos",
+                input.owner,
+                input.repo,
+                "contents",
+                ...(input.path ? input.path.split("/") : [""]),
+            ],
+            query: { ref: input.ref },
+        }),
+    }),
+    "repos.createOrUpdateFile": define({
+        method: "PUT",
+        repository: true,
+        input: z
+            .object({
+            ...repository,
+            path: contentPath,
+            message: z.string().min(1).max(4096),
+            content: base64,
+            sha: blobSha.optional(),
+            branch: gitRef.optional(),
+        })
+            .strict(),
+        response: z.object({
+            content: contentEntry.nullable(),
+            commit: z.object({
+                sha: text(64),
+                html_url: url.nullish(),
+                message: text(65_536).optional(),
+            }),
+        }),
+        // GitHub refuses workflow-file writes from a token without `workflow`.
+        scopes: (input) => /^\.github\/workflows\//i.test(input.path)
+            ? ["public_repo", "workflow"]
+            : ["public_repo"],
+        request: ({ owner, repo, path, ...body }) => ({
+            segments: ["repos", owner, repo, "contents", ...path.split("/")],
+            body,
+        }),
+    }),
+};
+export function isGitHubOperationId(value) {
+    return Object.hasOwn(githubOperations, value);
+}
+/**
+ * The api.github.com URL for an operation's path segments. Each segment is
+ * percent-encoded on its own, and the result must keep exactly that path on
+ * exactly this host, so no input can steer the token elsewhere.
+ */
+export function githubRequestUrl(segments, query = {}) {
+    const pathname = `/${segments.map(encodeURIComponent).join("/")}`;
+    const target = new URL(pathname, GITHUB_API_ORIGIN);
+    if (target.origin !== GITHUB_API_ORIGIN || target.pathname !== pathname)
+        throw new Error("GITHUB_PATH_REJECTED");
+    for (const [name, value] of Object.entries(query))
+        if (value !== undefined)
+            target.searchParams.set(name, value);
+    return target;
+}

package/dist/sdk/github/scopes.d.ts

@@ -0,0 +1,31 @@
+/**
+ * GitHub OAuth App scope rules shared by the connector route, the account page
+ * and the SDK. Pure and dependency-free so the SDK ships it unchanged.
+ */
+/** The scopes a Flow app may ask a user to add to their GitHub connection. */
+export declare const GITHUB_REQUESTABLE_SCOPES: readonly ["read:user", "user:email", "public_repo", "repo", "read:org", "gist", "workflow"];
+export type GitHubScope = (typeof GITHUB_REQUESTABLE_SCOPES)[number];
+/** What each scope lets Flow do, in the words the consent screen uses. */
+export declare const GITHUB_SCOPE_DESCRIPTIONS: {
+    readonly "read:user": "See your GitHub profile";
+    readonly "user:email": "See your email addresses";
+    readonly public_repo: "Read and change your public repositories, issues and pull requests";
+    readonly repo: "Read and change all your repositories, including private ones";
+    readonly "read:org": "See your organizations and team memberships";
+    readonly gist: "Create and edit your gists";
+    readonly workflow: "Change GitHub Actions workflow files";
+};
+/** What every connection asks for; more is requested only when a feature needs it. */
+export declare const GITHUB_BASELINE_SCOPES: readonly GitHubScope[];
+export declare function isGitHubScope(value: string): value is GitHubScope;
+/** Whether the granted set carries `scope` directly or through a parent scope. */
+export declare function hasGitHubScope(granted: readonly string[], scope: string): boolean;
+export declare function missingGitHubScopes<Scope extends string>(granted: readonly string[], required: readonly Scope[]): Scope[];
+/**
+ * The Flow ID account-page address that connects GitHub, or adds `scopes` to
+ * an existing connection. The one place this URL shape is written; `oauth=`
+ * is not used because it marks a return from the provider's callback.
+ */
+export declare function githubConsentUrl(issuer: string, scopes?: readonly GitHubScope[]): string;
+/** The scopes a consent URL asks for, or null when the URL is not one. */
+export declare function githubConsentRequest(search: string): GitHubScope[] | null;

package/dist/sdk/github/scopes.js

@@ -0,0 +1,70 @@
+/**
+ * GitHub OAuth App scope rules shared by the connector route, the account page
+ * and the SDK. Pure and dependency-free so the SDK ships it unchanged.
+ */
+/** The scopes a Flow app may ask a user to add to their GitHub connection. */
+export const GITHUB_REQUESTABLE_SCOPES = [
+    "read:user",
+    "user:email",
+    "public_repo",
+    "repo",
+    "read:org",
+    "gist",
+    "workflow",
+];
+/** What each scope lets Flow do, in the words the consent screen uses. */
+export const GITHUB_SCOPE_DESCRIPTIONS = {
+    "read:user": "See your GitHub profile",
+    "user:email": "See your email addresses",
+    public_repo: "Read and change your public repositories, issues and pull requests",
+    repo: "Read and change all your repositories, including private ones",
+    "read:org": "See your organizations and team memberships",
+    gist: "Create and edit your gists",
+    workflow: "Change GitHub Actions workflow files",
+};
+/** What every connection asks for; more is requested only when a feature needs it. */
+export const GITHUB_BASELINE_SCOPES = ["read:user"];
+// GitHub grants a parent scope's children implicitly, so a token holding
+// `repo` never lists `public_repo` even though it carries that authority.
+const impliedBy = new Map([
+    ["public_repo", ["repo"]],
+    ["read:user", ["user"]],
+    ["user:email", ["user"]],
+    ["read:org", ["write:org", "admin:org"]],
+]);
+export function isGitHubScope(value) {
+    return GITHUB_REQUESTABLE_SCOPES.some((scope) => scope === value);
+}
+/** Whether the granted set carries `scope` directly or through a parent scope. */
+export function hasGitHubScope(granted, scope) {
+    return (granted.includes(scope) ||
+        (impliedBy.get(scope) ?? []).some((parent) => granted.includes(parent)));
+}
+export function missingGitHubScopes(granted, required) {
+    return [
+        ...new Set(required.filter((scope) => !hasGitHubScope(granted, scope))),
+    ];
+}
+/**
+ * The Flow ID account-page address that connects GitHub, or adds `scopes` to
+ * an existing connection. The one place this URL shape is written; `oauth=`
+ * is not used because it marks a return from the provider's callback.
+ */
+export function githubConsentUrl(issuer, scopes = []) {
+    const url = new URL("/account", issuer);
+    url.searchParams.set("section", "connections");
+    url.searchParams.set("connect", "github");
+    const requested = [...new Set(scopes)];
+    if (requested.length)
+        url.searchParams.set("scopes", requested.join(" "));
+    return url.toString();
+}
+/** The scopes a consent URL asks for, or null when the URL is not one. */
+export function githubConsentRequest(search) {
+    const params = new URLSearchParams(search);
+    if (params.get("connect") !== "github")
+        return null;
+    return [
+        ...new Set((params.get("scopes") ?? "").split(/[\s,]+/).filter(isGitHubScope)),
+    ];
+}

package/dist/sdk/oauth/stores.d.ts

@@ -1,4 +1,5 @@
 import type { AppDb } from "../db/handle";
+import { oauthSession } from "../db/schema";
 export interface OAuthCredentialStore<T> {
     set(id: string, value: T): Promise<void>;
     get(id: string): Promise<T | undefined>;
@@ -13,4 +14,6 @@ export declare function createOAuthStores<State, Session>(database: AppDb, stora
 };
 export declare function cleanupOAuthCredentials(database: AppDb): Promise<void>;
 export declare function peekOAuthState<State>(database: AppDb, storageKey: string, providerId: string, id: string): Promise<State | undefined>;
+/** Opens a sealed `oauth_session` row read outside a store, such as one an erasure deleted. */
+export declare function openOAuthSessionRow<Session>(storageKey: string, row: Pick<typeof oauthSession.$inferSelect, "providerId" | "accountId" | "data" | "formatVersion">): Session;
 export declare function lockOAuthSession(database: AppDb, providerId: string, accountId: string): Promise<void>;

package/dist/sdk/oauth/stores.js

@@ -144,6 +144,10 @@ export async function peekOAuthState(database, storageKey, providerId, id) {
         return undefined;
     return createCredentialCipher(storageKey).open(row.data, JSON.stringify(["oauth-state", providerId, id]));
 }
+/** Opens a sealed `oauth_session` row read outside a store, such as one an erasure deleted. */
+export function openOAuthSessionRow(storageKey, row) {
+    return createCredentialCipher(storageKey).open(row.data, sessionContext(row.providerId, row.accountId, row.formatVersion));
+}
 function sessionContext(providerId, accountId, formatVersion) {
     if (formatVersion === 2)
         return JSON.stringify(["oauth-session", providerId, accountId]);