@openma/matter-gitlab 0.0.0-stage → 0.2.0

package/dist/bond/index.d.ts

@@ -0,0 +1,477 @@
+import { BondBinding, BondManifest, BondProvider, BondResourceCatalog, ProviderError, SecretRef, TokenGrant } from "@openma/matter/bond";
+import { Effect } from "effect";
+import { JsonValue, WorkEvent } from "@openma/matter";
+import { CredentialResolver } from "@openma/matter/credentials";
+import { IntegrationError, WorkIntegration } from "@openma/matter/integration";
+import { HttpEndpoint } from "@openma/matter/http";
+//#region src/bond/http.d.ts
+type Fetch = typeof globalThis.fetch;
+/**
+ * Normalizes a GitLab instance URL to its canonical https origin. Rejects
+ * plain http except for loopback hosts, and rejects paths, credentials,
+ * queries, and fragments.
+ */
+declare const canonicalOrigin: (input: string) => string;
+//#endregion
+//#region src/bond/oauth.d.ts
+/**
+ * What discovery verified. OAuth calls always use the instance's fixed
+ * `/oauth/authorize`, `/oauth/token`, and `/oauth/revoke` under `origin`, so
+ * discovery returns no endpoints that callers might follow elsewhere.
+ */
+interface GitLabInstance {
+  readonly origin: string;
+  /** Whether the instance enables the device authorization grant. */
+  readonly deviceFlow: boolean;
+}
+/**
+ * Reads OIDC discovery and requires authorization code with PKCE S256 and
+ * refresh tokens, and an issuer equal to the instance origin. Device flow is
+ * recorded when present; GitLab can disable it per instance.
+ */
+declare const discoverInstance: (origin: string, fetchImpl?: Fetch) => Effect.Effect<GitLabInstance, ProviderError>;
+interface Pkce {
+  readonly verifier: string;
+  readonly challenge: string;
+  readonly method: "S256";
+}
+/** A fresh PKCE verifier and its S256 challenge. Keep the verifier server-side. */
+declare const createPkce: () => Effect.Effect<Pkce>;
+interface AuthorizationUrlInput {
+  readonly origin: string;
+  readonly clientId: string;
+  readonly redirectUri: string;
+  readonly scopes: readonly string[];
+  /** Signed, single-use state bound to the user and ProviderApp. */
+  readonly state: string;
+  readonly codeChallenge: string;
+}
+declare const authorizationUrl: (input: AuthorizationUrlInput) => string;
+interface OAuthClient {
+  readonly origin: string;
+  readonly clientId: string;
+  /** Absent for public clients. */
+  readonly clientSecret?: string;
+  readonly fetch?: Fetch;
+  /** ISO now, for computing expiry. */
+  readonly clock?: () => string;
+}
+/** Exchanges an authorization code. A wrong verifier does not consume the code on GitLab. */
+declare const exchangeCode: (client: OAuthClient, input: {
+  readonly code: string;
+  readonly redirectUri: string;
+  readonly codeVerifier: string;
+}) => Effect.Effect<TokenGrant, ProviderError, never>;
+/**
+ * Refreshes a user token. GitLab rotates both tokens and invalidates the old
+ * access token immediately, and does not detect refresh-token reuse, so the
+ * caller must hold the Bond refresh lease.
+ */
+declare const refreshAccessToken: (client: OAuthClient, refreshToken: string) => Effect.Effect<TokenGrant, ProviderError, never>;
+/**
+ * Revokes one access or refresh token. GitLab (Doorkeeper) stores an access
+ * token and its refresh token as one record, so revoking either ends that
+ * pair only. Other tokens the same user holds for the same application keep
+ * working: on a live instance, revoking the previous token after a relink left
+ * the new one valid.
+ */
+declare const revokeToken: (client: OAuthClient, token: string) => Effect.Effect<undefined, ProviderError, never>;
+//#endregion
+//#region src/bond/tokens.d.ts
+/** `GET /api/v4/user`. Numeric `id` is the stable key; the rest is display data. */
+interface GitLabUser {
+  readonly id: string;
+  readonly username: string;
+  readonly name: string;
+  readonly commitEmail?: string;
+  readonly bot: boolean;
+  readonly identities: readonly {
+    readonly provider: string;
+    readonly externUid: string;
+  }[];
+}
+/** `GET /api/v4/personal_access_tokens/self`. Works for personal, project, and group access tokens. */
+interface GitLabTokenInfo {
+  readonly id: string;
+  readonly name: string;
+  readonly active: boolean;
+  readonly revoked: boolean;
+  readonly scopes: readonly string[];
+  /** `YYYY-MM-DD`, or undefined for a token without expiry. */
+  readonly expiresAt?: string;
+  readonly userId: string;
+}
+declare const readUser: (origin: string, token: string, fetchImpl?: Fetch) => Effect.Effect<GitLabUser, ProviderError>;
+declare const readTokenInfo: (origin: string, token: string, fetchImpl?: Fetch) => Effect.Effect<GitLabTokenInfo, ProviderError>;
+/** `DELETE /api/v4/personal_access_tokens/self`: a token revokes itself. */
+declare const revokeSelfToken: (origin: string, token: string, fetchImpl?: Fetch) => Effect.Effect<void, ProviderError>;
+interface TokenPolicy {
+  readonly allowedScopes: readonly string[];
+  readonly maxLifetimeDays: number;
+  /** ISO now. */
+  readonly now: string;
+}
+type TokenProblem = "inactive" | "revoked" | "no_expiry" | "expired" | "lifetime_exceeded" | "scope_not_allowed" | "not_a_bot" | "is_a_bot" | "user_mismatch";
+/** End of the UTC expiry day, which is when GitLab stops accepting the token. */
+declare const tokenExpiryInstant: (expiresAt: string) => string;
+/**
+ * Checks a pasted personal access token: active, scopes within the allowed
+ * set, an expiry within the maximum lifetime, and a human owner.
+ */
+declare const validatePersonalAccessToken: (info: GitLabTokenInfo, user: GitLabUser, policy: TokenPolicy) => readonly TokenProblem[];
+/**
+ * Checks a bot credential registered as an Installation: the same token
+ * checks, plus `bot: true` on its user. A human account's token is never
+ * accepted as an app principal.
+ */
+declare const validateBotCredential: (info: GitLabTokenInfo, user: GitLabUser, policy: TokenPolicy) => readonly TokenProblem[];
+//#endregion
+//#region src/bond/classify.d.ts
+type GitLabOperation = "fetch" | "push" | "read" | "open_mr" | "comment_mr";
+/**
+ * A normalized project reference. Paths are lower-cased and stripped of
+ * `.git`; numeric IDs stay numeric. Both forms name one project only after
+ * the application resolves them through GitLab.
+ */
+type ProjectRef = {
+  readonly kind: "id";
+  readonly id: number;
+} | {
+  readonly kind: "path";
+  readonly path: string;
+};
+type GitLabRequestClass = {
+  readonly allow: true;
+  readonly projectRef: ProjectRef;
+  readonly operation: GitLabOperation;
+  /** `git` for smart HTTP, `rest` for `/api/v4`. */
+  readonly surface: "git" | "rest";
+  /**
+   * For `rest`: the validated path after `/api/v4/projects/<ref>`, to
+   * append to the resolved numeric project ID. For `open_mr`, the proxy
+   * must also check the body with `mergeRequestBodyProblem`.
+   */
+  readonly restTail?: string;
+} | {
+  readonly allow: false;
+  readonly reason: string;
+};
+/**
+ * Classifies one request in GitLab's own URL shape. Allows git smart HTTP
+ * fetch and push, REST reads of a project, merge request creation, and
+ * merge request notes. Denies GraphQL, LFS, archives, raw files, and every
+ * other route.
+ */
+declare const classifyGitLabRequest: (method: string, url: string | URL) => GitLabRequestClass;
+/**
+ * GitLab lets `POST /projects/:id/merge_requests` name another project in
+ * `target_project_id`, so the URL alone does not bound where the merge
+ * request opens. Returns the reason to deny, or undefined when the body
+ * targets the classified project.
+ *
+ * Pass the parsed JSON object or form body and the numeric ID the URL's
+ * project reference resolved to, then forward the body you checked
+ * (re-serialized), never the raw bytes: parsers disagree on repeated keys.
+ * For the same reason a form that repeats `target_project_id`, or uses a
+ * variant such as `target_project_id[]`, is denied.
+ */
+declare const mergeRequestBodyProblem: (body: unknown, resolvedProjectId: number) => string | undefined;
+//#endregion
+//#region src/bond/receive-pack.d.ts
+declare const ZERO_OID: string;
+interface ReceivePackCommand {
+  readonly oldId: string;
+  readonly newId: string;
+  readonly ref: string;
+}
+interface ReceivePackHead {
+  readonly commands: readonly ReceivePackCommand[];
+  readonly capabilities: readonly string[];
+  readonly options: readonly string[];
+  /** Bytes consumed by the head. The pack starts here. */
+  readonly headLength: number;
+}
+type ReceivePackParse = {
+  readonly _tag: "Complete";
+  readonly head: ReceivePackHead;
+} | {
+  readonly _tag: "Incomplete";
+} | {
+  readonly _tag: "Malformed";
+  readonly reason: string;
+};
+/** Bounds on a hostile head. Exceeding one is Malformed, never Incomplete. */
+interface ReceivePackLimits {
+  /** Default 1 MiB. */
+  readonly maxHeadBytes?: number;
+  /** Default 1000. */
+  readonly maxCommands?: number;
+  /** Default 100. */
+  readonly maxOptions?: number;
+}
+/**
+ * A strict subset of `git check-ref-format`: a full `refs/` name with no
+ * control characters, no characters git forbids, no empty, dot-leading, or
+ * `.lock` components, no `..`, and no `@{`.
+ */
+declare const isValidRefName: (ref: string) => boolean;
+interface ReceivePackHeadParser {
+  /** Feeds the next chunk of the request body. */
+  readonly push: (chunk: Uint8Array) => ReceivePackParse;
+  /**
+   * Bytes after the head in the chunk that completed it: the start of the
+   * pack. Later chunks are not buffered; stream them upstream directly.
+   */
+  readonly remainder: () => Uint8Array;
+}
+/**
+ * Incremental receive-pack head parser. Each byte is examined once, and only
+ * an unfinished pkt-line is buffered, so a head fed in many small chunks
+ * costs linear time. Capabilities are the union over every command line, as
+ * in git's `read_head`: a client cannot hide `push-options` behind a later
+ * line without them.
+ */
+declare const makeReceivePackHeadParser: (limits?: ReceivePackLimits) => ReceivePackHeadParser;
+/**
+ * Parses as much of the receive-pack head as `bytes` holds. A convenience
+ * for a buffered prefix; streaming proxies should use
+ * `makeReceivePackHeadParser` and feed chunks as they arrive.
+ */
+declare const parseReceivePackHead: (bytes: Uint8Array, limits?: ReceivePackLimits) => ReceivePackParse;
+interface PushPolicy {
+  /** The project's default branch name, refreshed from GitLab by project ID. */
+  readonly defaultBranch: string;
+  /** Allow pushing to the default branch. Default false. */
+  readonly allowDefaultBranch?: boolean;
+  /** Only branches with this prefix may be updated, when set. */
+  readonly branchPrefix?: string;
+  /** Label every merge request created by push option must carry. */
+  readonly requiredMergeRequestLabel: string;
+  /** Whether `merge_request.*` options are allowed at all (the `open_mr` grant). */
+  readonly allowMergeRequestOptions: boolean;
+}
+/**
+ * Returns the reason a push is denied, or undefined when it is allowed.
+ * Denies tags and other non-branch refs, deletions, the default branch, and
+ * any push option outside the merge request allow-list. GitLab still applies
+ * its own branch protection afterwards.
+ */
+declare const evaluatePush: (head: ReceivePackHead, policy: PushPolicy) => string | undefined;
+//#endregion
+//#region src/bond/attribution.d.ts
+interface CommitIdentity {
+  readonly name: string;
+  readonly email: string;
+}
+/** The commit author for a GitLab user: their name and `commit_email`. */
+declare const commitAuthor: (user: {
+  readonly name: string;
+  readonly username: string;
+  readonly commitEmail?: string;
+}) => CommitIdentity;
+/** `Assisted-by: <app> <session URL>`, added to every commit. */
+declare const assistedByTrailer: (appName: string, sessionUrl: string) => string;
+/** `Co-authored-by` for a participant or, with the app principal, the requester. */
+declare const coAuthoredByTrailer: (who: CommitIdentity) => string;
+/** Description footer for merge requests and comments. */
+declare const mergeRequestFooter: (input: {
+  readonly appName: string;
+  readonly sessionUrl: string;
+  /** Username of the requesting user; set when the app principal authors. */
+  readonly requestedBy?: string;
+}) => string;
+/** `git push -o` options that create a labelled merge request. */
+declare const mergeRequestPushOptions: (input: {
+  readonly target: string;
+  readonly title: string;
+  readonly description: string;
+  readonly label: string;
+}) => readonly string[];
+//#endregion
+//#region src/bond/provider.d.ts
+interface GitLabBondProviderOptions {
+  readonly fetch?: Fetch;
+  readonly clock?: () => string;
+  /** Resolves `oauth.clientSecret` references. Omit for public clients. */
+  readonly resolveSecret?: (ref: SecretRef) => Effect.Effect<string, unknown>;
+}
+/**
+ * Bond's GitLab provider. A configured `oauth.clientSecret` requires
+ * `resolveSecret`; the provider never silently degrades to a public client. GitLab has no delegation marker, so user-principal
+ * writes need the ProviderApp's `allowUserPrincipalOutput`. The app principal
+ * is a registered bot credential stored on the Installation; GitLab 17.1
+ * cannot rotate it from the bot itself, so an administrator replaces it.
+ */
+declare const makeGitLabBondProvider: (options?: GitLabBondProviderOptions) => BondProvider;
+//#endregion
+//#region src/bond/resources.d.ts
+/** Minimum GitLab access level per operation: 20 Reporter, 30 Developer. */
+declare const GITLAB_MIN_ACCESS_LEVEL: Readonly<Record<GitLabOperation, number>>;
+declare const gitlabManifest: BondManifest;
+interface GitLabResourceCatalogOptions {
+  readonly fetch?: Fetch;
+}
+/**
+ * Projects as Bond resources, with IDs `project:<numeric id>`. Paths are
+ * display data only. `list` returns projects where the token holds at least
+ * Reporter; `validate` checks the access level each operation needs and
+ * refuses writes to archived projects. An instance administrator without a
+ * membership reports no access level and is treated as having none.
+ */
+declare const makeGitLabResourceCatalog: (options?: GitLabResourceCatalogOptions) => BondResourceCatalog;
+/** The provider, manifest, and resource catalog a host registers for GitLab. */
+declare const makeGitLabBinding: (options?: GitLabBondProviderOptions) => BondBinding;
+//#endregion
+//#region src/bond/integration/client.d.ts
+/**
+ * What a GitLab call needs for one authority: the instance and a token with
+ * API access (a Bond's app principal token, or a test token).
+ */
+interface GitLabCredentials {
+  /** The instance root, for example `https://gitlab.example.com`. */
+  readonly baseUrl: string;
+  readonly token: string;
+}
+type GitLabCredentialResolver = CredentialResolver<GitLabCredentials>;
+type GitLabCredentialSource = (authority: string) => GitLabCredentials | PromiseLike<GitLabCredentials> | Effect.Effect<GitLabCredentials, unknown>;
+type GitLabCredentialOption = GitLabCredentials | GitLabCredentialResolver | GitLabCredentialSource;
+type GitLabCredentialsFor = (authority: string) => Effect.Effect<GitLabCredentials, IntegrationError>;
+declare const makeGitLabCredentialsFor: (option: GitLabCredentialOption) => GitLabCredentialsFor;
+interface GitLabResponse {
+  readonly payload: JsonValue;
+  readonly headers: Headers;
+}
+declare const makeGitLabClient: (input: {
+  readonly credentialsFor: GitLabCredentialsFor;
+  readonly fetch: typeof globalThis.fetch;
+  readonly clock: () => string;
+}) => {
+  request: (options: {
+    readonly authority: string;
+    readonly method: "DELETE" | "GET" | "POST" | "PUT";
+    readonly path: string;
+    readonly body?: Readonly<Record<string, unknown>>;
+  }) => Effect.Effect<GitLabResponse, IntegrationError>;
+};
+type GitLabClient = ReturnType<typeof makeGitLabClient>;
+//#endregion
+//#region src/bond/integration/delivery.d.ts
+/** Every Effect operation `deliver` accepts. */
+declare const GITLAB_OPERATIONS: readonly ["merge_request.note.create", "merge_request.discussion.reply", "issue.note.create", "issue.discussion.reply"];
+type GitLabEffectOperation = (typeof GITLAB_OPERATIONS)[number];
+/**
+ * Delivers GitLab Effects. Every input names the `authority` whose
+ * credentials post the note, the `projectId` (numeric id or full path), the
+ * merge request or issue `iid`, and a non-empty `body`. Discussion replies
+ * also name the `discussionId`; replying to a single comment turns it into a
+ * thread.
+ */
+declare const makeGitLabDelivery: (client: Pick<GitLabClient, "request">) => WorkIntegration["deliver"];
+//#endregion
+//#region src/bond/integration/events.d.ts
+/** Every Event type `ingest` can produce. */
+declare const GITLAB_EVENT_TYPES: readonly string[];
+/**
+ * Turns a verified `GitLabWebhookInput` into one WorkEvent. Inputs of another
+ * kind produce no Events. The Event id combines the authority and the
+ * delivery id, so a GitLab retry is the same Event.
+ */
+declare const normalizeGitLabEvents: (input: unknown, clock: () => string) => Effect.Effect<readonly WorkEvent[], IntegrationError>;
+//#endregion
+//#region src/bond/integration/http.d.ts
+declare const GitLabHttpIngressError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+  readonly _tag: "GitLabHttpIngressError";
+} & Readonly<A>;
+declare class GitLabHttpIngressError extends GitLabHttpIngressError_base<{
+  readonly message: string;
+  readonly status: 400 | 401;
+  readonly cause?: unknown;
+}> {}
+declare const GitLabHttpSubmissionError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+  readonly _tag: "GitLabHttpSubmissionError";
+} & Readonly<A>;
+declare class GitLabHttpSubmissionError extends GitLabHttpSubmissionError_base<{
+  readonly message: string;
+  readonly status: 503;
+  readonly cause?: unknown;
+}> {}
+/** One verified GitLab webhook delivery, ready for `integration.ingest`. */
+interface GitLabWebhookInput {
+  readonly kind: "gitlab.webhook";
+  /**
+   * Who received the webhook, chosen by the host (for example a Bond id).
+   * It becomes the Event source authority and selects credentials for replies.
+   */
+  readonly authority: string;
+  /** The `X-Gitlab-Event` header, for example `Merge Request Hook`. */
+  readonly eventName: string;
+  /** Stable across GitLab retries; see `decodeGitLabHttpRequest`. */
+  readonly deliveryId: string;
+  /** The `X-Gitlab-Instance` header (GitLab 15.5+), when present. */
+  readonly instance?: string;
+  readonly payload: JsonValue;
+}
+interface GitLabHttpEndpointOptions {
+  /** The secret token configured on the GitLab webhook. */
+  readonly webhookToken: string;
+  readonly authority: string;
+  readonly path?: string;
+  readonly submit: (input: GitLabWebhookInput) => Promise<unknown>;
+}
+/**
+ * Compares the `X-Gitlab-Token` header with the configured secret token in
+ * constant time. Both values are hashed first, so the comparison does not
+ * reveal the secret's length either. An empty configured token never matches.
+ */
+declare const verifyGitLabToken: (input: {
+  readonly webhookToken: string;
+  readonly received: string;
+}) => Effect.Effect<boolean, GitLabHttpIngressError>;
+/**
+ * Verifies and decodes one GitLab webhook request. The delivery id is the
+ * first of `webhook-id` and `Idempotency-Key` (both stable across retries,
+ * GitLab 17.4+) and `X-Gitlab-Event-UUID` (GitLab 14.8+).
+ */
+declare const decodeGitLabHttpRequest: (request: Request, options: Pick<GitLabHttpEndpointOptions, "webhookToken" | "authority">) => Effect.Effect<GitLabWebhookInput, GitLabHttpIngressError>;
+/**
+ * A webhook endpoint for one GitLab authority. Hosts that serve many
+ * authorities from one route call `decodeGitLabHttpRequest` with the token
+ * and authority they look up for the request instead.
+ */
+declare const makeGitLabHttpEndpoint: (options: GitLabHttpEndpointOptions) => HttpEndpoint;
+//#endregion
+//#region src/bond/integration/integration.d.ts
+interface GitLabIntegrationOptions {
+  /**
+   * Credentials for replies: fixed `{ baseUrl, token }`, or a resolver keyed
+   * by the Event authority (for example a Bond's app principal).
+   */
+  readonly credentials: GitLabCredentialOption;
+  readonly fetch?: typeof globalThis.fetch;
+  readonly clock?: () => string;
+}
+/**
+ * The GitLab work integration: `ingest` takes a `GitLabWebhookInput` from
+ * `decodeGitLabHttpRequest`, and `deliver` posts merge request and issue
+ * notes.
+ */
+declare const makeGitLabIntegration: (options: GitLabIntegrationOptions) => WorkIntegration;
+//#endregion
+//#region src/bond/integration/templates.d.ts
+/**
+ * Reviews a merge request when it opens, reopens, or receives new commits,
+ * and posts the review as a note. Title or label edits do not trigger a
+ * review. Draft merge requests are skipped unless `skipDrafts` is false.
+ */
+declare const gitlabMergeRequestReview: import("@openma/matter-loop").Loop;
+/**
+ * Answers a merge request comment that mentions the Agent's GitLab user, in
+ * the same thread. System notes and the Agent's own notes are ignored, so a
+ * reply never triggers another reply.
+ */
+declare const gitlabMention: import("@openma/matter-loop").Loop;
+/** The GitLab templates, in the order a console lists them. */
+declare const gitlabTemplates: readonly [import("@openma/matter-loop").Loop, import("@openma/matter-loop").Loop];
+//#endregion
+export { type AuthorizationUrlInput, type CommitIdentity, type Fetch, GITLAB_EVENT_TYPES, GITLAB_MIN_ACCESS_LEVEL, GITLAB_OPERATIONS, type GitLabBondProviderOptions, type GitLabClient, type GitLabCredentialOption, type GitLabCredentialResolver, type GitLabCredentialSource, type GitLabCredentials, type GitLabEffectOperation, type GitLabHttpEndpointOptions, GitLabHttpIngressError, GitLabHttpSubmissionError, type GitLabInstance, type GitLabIntegrationOptions, type GitLabOperation, type GitLabRequestClass, type GitLabResourceCatalogOptions, type GitLabTokenInfo, type GitLabUser, type GitLabWebhookInput, type OAuthClient, type Pkce, type ProjectRef, type PushPolicy, type ReceivePackCommand, type ReceivePackHead, type ReceivePackHeadParser, type ReceivePackLimits, type ReceivePackParse, type TokenPolicy, type TokenProblem, ZERO_OID, assistedByTrailer, authorizationUrl, canonicalOrigin, classifyGitLabRequest, coAuthoredByTrailer, commitAuthor, createPkce, decodeGitLabHttpRequest, discoverInstance, evaluatePush, exchangeCode, gitlabManifest, gitlabMention, gitlabMergeRequestReview, gitlabTemplates, isValidRefName, makeGitLabBinding, makeGitLabBondProvider, makeGitLabClient, makeGitLabCredentialsFor, makeGitLabDelivery, makeGitLabHttpEndpoint, makeGitLabIntegration, makeGitLabResourceCatalog, makeReceivePackHeadParser, mergeRequestBodyProblem, mergeRequestFooter, mergeRequestPushOptions, normalizeGitLabEvents, parseReceivePackHead, readTokenInfo, readUser, refreshAccessToken, revokeSelfToken, revokeToken, tokenExpiryInstant, validateBotCredential, validatePersonalAccessToken, verifyGitLabToken };
+//# sourceMappingURL=index.d.ts.map