@capybara-hq/kernel 0.0.0-stage → 0.1.0-rc.0

package/dist/net/public-address.js

@@ -0,0 +1,271 @@
+import { lookup as dnsLookup } from "node:dns/promises";
+import { BlockList, isIP } from "node:net";
+/**
+ * Public-address checks for downloads whose URL comes from a marketplace or an admin (spec §5.1).
+ * A host is resolved once, every resolved address must be public, and the caller connects to the
+ * checked addresses only (see `safe-fetch.ts`), so a DNS answer that changes between check and
+ * connect (DNS rebinding, e.g. `10.0.0.1.nip.io`) cannot reach a private address.
+ *
+ * The blocked ranges are those of `plugins/sandbox-docker/egress-proxy/proxy.mjs`, ported here
+ * because the kernel must not import from a plugin. IPv6 addresses that embed an IPv4 address
+ * (v4-mapped `::ffff:0:0/96`, v4-compatible `::/96`, NAT64 `64:ff9b::/96`, 6to4 `2002::/16`) are
+ * judged by the embedded IPv4 address; anything unparseable is refused. One addition over proxy.mjs:
+ * SIIT IPv4-translated addresses (`::ffff:0:a.b.c.d`, `::ffff:0:0:0/96`, RFC 2765) are also judged by
+ * the embedded IPv4 address (proxy.mjs falls through to the IPv6 table, where they are not blocked);
+ * a host behind a SIIT translator could otherwise reach a private IPv4 address.
+ *
+ * Link-local addresses (`169.254.0.0/16`, including cloud metadata, and `fe80::/10`) stay forbidden
+ * whatever the exemptions: no internal mirror lives there.
+ */
+const BLOCKED_V4 = [
+    ["0.0.0.0", 8], // unspecified / this network
+    ["10.0.0.0", 8],
+    ["100.64.0.0", 10], // CGNAT
+    ["127.0.0.0", 8],
+    ["169.254.0.0", 16], // link-local, including cloud metadata 169.254.169.254
+    ["172.16.0.0", 12],
+    ["192.0.0.0", 24],
+    ["192.0.2.0", 24],
+    ["192.88.99.0", 24],
+    ["192.168.0.0", 16],
+    ["198.18.0.0", 15],
+    ["198.51.100.0", 24],
+    ["203.0.113.0", 24],
+    ["224.0.0.0", 4], // multicast
+    ["240.0.0.0", 4], // reserved and broadcast
+];
+const BLOCKED_V6 = [
+    ["::", 128],
+    ["::1", 128],
+    ["100::", 64],
+    ["2001:db8::", 32],
+    ["fc00::", 7], // ULA
+    ["fe80::", 10], // link-local
+    ["fec0::", 10],
+    ["ff00::", 8], // multicast
+];
+// Read-only after construction: address tables, not shared mutable state.
+const blocked = new BlockList();
+for (const [a, p] of BLOCKED_V4)
+    blocked.addSubnet(a, p, "ipv4");
+for (const [a, p] of BLOCKED_V6)
+    blocked.addSubnet(a, p, "ipv6");
+const linkLocal = new BlockList();
+linkLocal.addSubnet("169.254.0.0", 16, "ipv4");
+linkLocal.addSubnet("fe80::", 10, "ipv6");
+/** An IPv6 address as its 8 16-bit groups; null when it cannot be parsed. */
+function v6Groups(ip) {
+    let s = ip.toLowerCase();
+    const zone = s.indexOf("%");
+    if (zone >= 0)
+        s = s.slice(0, zone);
+    // a trailing dotted IPv4 (::ffff:1.2.3.4)
+    const m = /^(.*:)(\d+)\.(\d+)\.(\d+)\.(\d+)$/.exec(s);
+    if (m) {
+        const [a = 0, b = 0, c = 0, d = 0] = m.slice(2).map(Number);
+        if ([a, b, c, d].some((x) => x > 255))
+            return null;
+        s = `${m[1]}${((a << 8) | b).toString(16)}:${((c << 8) | d).toString(16)}`;
+    }
+    const halves = s.split("::");
+    if (halves.length > 2)
+        return null;
+    const head = halves[0] ? halves[0].split(":") : [];
+    const tail = halves.length === 2 && halves[1] ? halves[1].split(":") : [];
+    const fill = halves.length === 2 ? 8 - head.length - tail.length : 0;
+    if (fill < 0)
+        return null;
+    const parts = [...head, ...Array(fill).fill("0"), ...tail];
+    if (!parts.every((g) => /^[0-9a-f]{1,4}$/.test(g)))
+        return null;
+    const groups = parts.map((g) => Number.parseInt(g, 16));
+    return groups.length === 8 ? groups : null;
+}
+const v4Of = (hi, lo) => `${hi >> 8}.${hi & 0xff}.${lo >> 8}.${lo & 0xff}`;
+/**
+ * Whether `ip` falls in `table`, judging an IPv6 address that embeds an IPv4 address by the
+ * embedded one. Anything unparseable (including an IPv4 address with a `%` zone) counts as inside.
+ */
+function inTable(ip, table) {
+    if (isIP(ip) === 4)
+        return table.check(ip, "ipv4");
+    if (isIP(ip.split("%")[0] ?? "") !== 6)
+        return true;
+    const g = v6Groups(ip);
+    if (g === null)
+        return true;
+    const zeros = (from, to) => g.slice(from, to).every((x) => x === 0);
+    const [g0, g1, g2, , g4, g5, g6 = 0, g7 = 0] = g;
+    // v4-mapped ::ffff:a.b.c.d
+    if (zeros(0, 5) && g5 === 0xffff)
+        return inTable(v4Of(g6, g7), table);
+    // SIIT ::ffff:0:a.b.c.d (not unwrapped by proxy.mjs; see the file header)
+    if (zeros(0, 4) && g4 === 0xffff && g5 === 0)
+        return inTable(v4Of(g6, g7), table);
+    // v4-compatible ::a.b.c.d (:: and ::1 are left to the IPv6 table)
+    if (zeros(0, 6) && (g6 !== 0 || g7 > 1))
+        return inTable(v4Of(g6, g7), table);
+    // NAT64 64:ff9b::a.b.c.d
+    if (g0 === 0x64 && g1 === 0xff9b)
+        return inTable(v4Of(g6, g7), table);
+    // 6to4 2002:AABB:CCDD::
+    if (g0 === 0x2002)
+        return inTable(v4Of(g1 ?? 0, g2 ?? 0), table);
+    return table.check(g.map((x) => x.toString(16)).join(":"), "ipv6");
+}
+/** Whether connecting to this (resolved) IP is forbidden: private, loopback, reserved, or unparseable. */
+export function isForbiddenAddress(ip) {
+    return inTable(ip, blocked);
+}
+/** Link-local (incl. cloud metadata 169.254.169.254) or unparseable: forbidden whatever the exemptions. */
+export function isLinkLocalAddress(ip) {
+    return inTable(ip, linkLocal);
+}
+/** A hostname normalized for comparison: lower case, no IPv6 brackets, no trailing dots. */
+export function normalizeHost(host) {
+    let h = host.trim().toLowerCase();
+    if (h.startsWith("[") && h.endsWith("]"))
+        h = h.slice(1, -1);
+    while (h.endsWith("."))
+        h = h.slice(0, -1);
+    return h;
+}
+/** `localhost`, `127.0.0.0/8` or `::1` (as written in a URL). */
+export function isLoopbackHost(host) {
+    const h = normalizeHost(host);
+    return h === "localhost" || h === "::1" || (isIP(h) === 4 && h.startsWith("127."));
+}
+/** A download refused by the network rules. English message, safe to show. */
+export class NetDeniedError extends Error {
+    code;
+    host;
+    constructor(code, host, message) {
+        super(message);
+        this.code = code;
+        this.host = host;
+        this.name = "NetDeniedError";
+    }
+}
+const defaultLookup = (host) => dnsLookup(host, { all: true, verbatim: true });
+/** The shortest prefix an `allowPrivateHosts` CIDR may have, per family. */
+export const MIN_CIDR_PREFIX = { ipv4: 8, ipv6: 16 };
+/** A syntactically valid `addr/prefix` CIDR as [address, prefix, family], else undefined. */
+export function parseCidr(s) {
+    const m = /^([^/]+)\/(\d{1,3})$/.exec(s.trim());
+    if (!m)
+        return undefined;
+    const addr = m[1].toLowerCase();
+    const prefix = Number(m[2]);
+    const family = isIP(addr);
+    if (family === 4 && prefix <= 32)
+        return [addr, prefix, "ipv4"];
+    if (family === 6 && prefix <= 128)
+        return [addr, prefix, "ipv6"];
+    return undefined;
+}
+const HOSTNAME = /^(?=.{1,253}$)([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*$/;
+/**
+ * Why a `marketplaces.allowPrivateHosts` entry is invalid (English), or null when it is a hostname,
+ * an IP address or a CIDR no broader than /8 (IPv4) or /16 (IPv6).
+ */
+export function privateHostEntryProblem(entry) {
+    const cidr = parseCidr(entry);
+    if (cidr) {
+        const [, prefix, family] = cidr;
+        const min = MIN_CIDR_PREFIX[family];
+        return prefix < min
+            ? `the CIDR ${entry.trim()} is too broad: use a prefix of at least /${min} for ${family === "ipv4" ? "IPv4" : "IPv6"}`
+            : null;
+    }
+    const h = normalizeHost(entry);
+    if (isIP(h) !== 0 || HOSTNAME.test(h))
+        return null;
+    return "must be a hostname, an IP address or a CIDR such as 10.1.0.0/16";
+}
+/** A valid `marketplaces.allowPrivateHosts` entry (see {@link privateHostEntryProblem}). */
+export function isPrivateHostEntry(entry) {
+    return privateHostEntryProblem(entry) === null;
+}
+function exemptions(host, policy) {
+    const cidrs = new BlockList();
+    let all = false;
+    const literal = isIP(host) !== 0;
+    // a loopback host under allowInsecureLoopback may resolve to loopback addresses only
+    if (policy.allowInsecureLoopback && isLoopbackHost(host)) {
+        cidrs.addSubnet("127.0.0.0", 8, "ipv4");
+        cidrs.addAddress("::1", "ipv6");
+    }
+    for (const entry of policy.allowPrivateHosts) {
+        if (!isPrivateHostEntry(entry))
+            continue;
+        const cidr = parseCidr(entry);
+        const name = normalizeHost(entry);
+        if (cidr) {
+            // IP and CIDR entries match IP-literal hosts only
+            if (literal)
+                cidrs.addSubnet(...cidr);
+        }
+        else if (isIP(name) !== 0) {
+            if (literal)
+                cidrs.addAddress(name, isIP(name) === 4 ? "ipv4" : "ipv6");
+        }
+        else if (name === host) {
+            all = true;
+        }
+    }
+    for (const origin of policy.trustedOrigins) {
+        try {
+            if (normalizeHost(new URL(origin).hostname) === host)
+                all = true;
+        }
+        catch {
+            // an unparseable origin trusts nothing
+        }
+    }
+    return { all, cidrs };
+}
+function allowedBy(cidrs, ip) {
+    const family = isIP(ip);
+    if (family === 4)
+        return cidrs.check(ip, "ipv4");
+    if (family === 6) {
+        if (cidrs.check(ip, "ipv6"))
+            return true;
+        // a v4-mapped answer also matches an IPv4 CIDR
+        const g = v6Groups(ip);
+        if (g?.slice(0, 5).every((x) => x === 0) && g[5] === 0xffff) {
+            return cidrs.check(v4Of(g[6] ?? 0, g[7] ?? 0), "ipv4");
+        }
+    }
+    return false;
+}
+/**
+ * Resolves `host` (an IP literal is taken as is) and returns every address, in resolution order,
+ * after checking that each is public or exempt by `policy`. Throws {@link NetDeniedError}
+ * `net.dns_failed` (no answer) or `net.private_address` (some address is private and not exempt).
+ */
+export async function resolvePublic(host, policy, lookup = defaultLookup) {
+    const h = normalizeHost(host);
+    let addrs;
+    if (isIP(h) !== 0) {
+        addrs = [h];
+    }
+    else {
+        try {
+            addrs = (await lookup(h)).map((a) => a.address);
+        }
+        catch {
+            throw new NetDeniedError("net.dns_failed", h, `Cannot resolve ${h}.`);
+        }
+        if (addrs.length === 0)
+            throw new NetDeniedError("net.dns_failed", h, `Cannot resolve ${h}.`);
+    }
+    const ex = exemptions(h, policy);
+    const refused = (a) => isForbiddenAddress(a) && (isLinkLocalAddress(a) || (!ex.all && !allowedBy(ex.cidrs, a)));
+    if (addrs.some(refused)) {
+        throw new NetDeniedError("net.private_address", h, addrs.some(isLinkLocalAddress)
+            ? `Access to ${h} is refused: it resolves to a link-local address, which is never allowed.`
+            : `Access to ${h} is refused: it resolves to a private or reserved address (add the hostname to marketplaces.allowPrivateHosts to allow an internal host).`);
+    }
+    return addrs;
+}

package/dist/net/safe-fetch.d.ts

@@ -0,0 +1,38 @@
+import { Agent } from "undici";
+import { type LookupFn, type NetPolicy } from "./public-address.js";
+/**
+ * `fetch` for URLs that come from a marketplace or an admin (spec §5.1):
+ * - https only; plain http only for a loopback host under `allowInsecureLoopback` (testing);
+ * - the host is resolved once by {@link resolvePublic} and the connection goes to the checked
+ *   addresses: a per-request undici `Agent` whose `connect.lookup` answers only those addresses,
+ *   so there is no second DNS lookup (no rebinding), while the Host header and TLS SNI keep the
+ *   original hostname;
+ * - with `policy.proxy` (`net.httpsProxy`), an https URL whose host is not loopback and not in
+ *   `noProxy` tunnels through the proxy (`proxy.ts`) instead: the host is not resolved locally
+ *   (the proxy resolves it and owns SSRF protection for the resolved address), but an IP-literal
+ *   host is still checked against the private ranges and `allowPrivateHosts`;
+ * - redirects are never followed: a 3xx (other than 304) is {@link NetDeniedError} `net.redirect`;
+ * - with `maxBytes`, a declared or streamed body over the limit is {@link NetBodyTooLargeError}.
+ */
+/** The response body is larger than `maxBytes`. */
+export declare class NetBodyTooLargeError extends Error {
+    readonly maxBytes: number;
+    constructor(maxBytes: number);
+}
+/**
+ * An undici dispatcher whose connections go only to `ips` (already checked), whatever the URL's
+ * hostname; the hostname still names the Host header and TLS SNI. One agent per download.
+ */
+export declare function pinnedAgent(ips: string[], tls?: {
+    ca?: string | string[];
+}): Agent;
+export declare function safeFetch(url: string, init: RequestInit & {
+    signal: AbortSignal;
+}, policy: NetPolicy, opts?: {
+    lookup?: LookupFn;
+    maxBytes?: number;
+    /** Tests only: wraps the pinned dispatcher (defaults to {@link pinnedAgent}). */
+    dispatcherFor?: (ips: string[]) => Agent;
+    /** Tests only: builds the proxy dispatcher (defaults to {@link proxyAgent}). */
+    proxyDispatcherFor?: (proxyUrl: string) => Agent;
+}): Promise<Response>;

package/dist/net/safe-fetch.js

@@ -0,0 +1,140 @@
+import { isIP } from "node:net";
+import { Agent, fetch as undiciFetch } from "undici";
+import { bypassesProxy, proxyAgent } from "./proxy.js";
+import { isLoopbackHost, NetDeniedError, normalizeHost, resolvePublic, } from "./public-address.js";
+/**
+ * `fetch` for URLs that come from a marketplace or an admin (spec §5.1):
+ * - https only; plain http only for a loopback host under `allowInsecureLoopback` (testing);
+ * - the host is resolved once by {@link resolvePublic} and the connection goes to the checked
+ *   addresses: a per-request undici `Agent` whose `connect.lookup` answers only those addresses,
+ *   so there is no second DNS lookup (no rebinding), while the Host header and TLS SNI keep the
+ *   original hostname;
+ * - with `policy.proxy` (`net.httpsProxy`), an https URL whose host is not loopback and not in
+ *   `noProxy` tunnels through the proxy (`proxy.ts`) instead: the host is not resolved locally
+ *   (the proxy resolves it and owns SSRF protection for the resolved address), but an IP-literal
+ *   host is still checked against the private ranges and `allowPrivateHosts`;
+ * - redirects are never followed: a 3xx (other than 304) is {@link NetDeniedError} `net.redirect`;
+ * - with `maxBytes`, a declared or streamed body over the limit is {@link NetBodyTooLargeError}.
+ */
+/** The response body is larger than `maxBytes`. */
+export class NetBodyTooLargeError extends Error {
+    maxBytes;
+    constructor(maxBytes) {
+        super(`the response is larger than ${maxBytes} bytes`);
+        this.maxBytes = maxBytes;
+        this.name = "NetBodyTooLargeError";
+    }
+}
+/** A `net.connect` lookup that answers only the checked addresses, whatever the hostname. */
+function pinnedLookup(ips) {
+    const all = ips.map((address) => ({
+        address,
+        family: isIP(address) === 6 ? 6 : 4,
+    }));
+    return (_hostname, options, callback) => {
+        if (options.all)
+            callback(null, all);
+        else
+            callback(null, all[0]?.address ?? "", all[0]?.family ?? 4);
+    };
+}
+/**
+ * An undici dispatcher whose connections go only to `ips` (already checked), whatever the URL's
+ * hostname; the hostname still names the Host header and TLS SNI. One agent per download.
+ */
+export function pinnedAgent(ips, tls = {}) {
+    return new Agent({
+        connect: { lookup: pinnedLookup(ips), ...(tls.ca !== undefined && { ca: tls.ca }) },
+    });
+}
+const NULL_BODY_STATUS = new Set([101, 103, 204, 205, 304]);
+function capBody(body, maxBytes) {
+    let seen = 0;
+    return body.pipeThrough(new TransformStream({
+        transform(chunk, controller) {
+            seen += chunk.byteLength;
+            if (seen > maxBytes)
+                controller.error(new NetBodyTooLargeError(maxBytes));
+            else
+                controller.enqueue(chunk);
+        },
+    }));
+}
+export async function safeFetch(url, init, policy, opts = {}) {
+    let target;
+    try {
+        target = new URL(url);
+    }
+    catch {
+        throw new NetDeniedError("net.insecure_url", "", "The URL is not valid.");
+    }
+    const host = normalizeHost(target.hostname);
+    const insecureOk = policy.allowInsecureLoopback && target.protocol === "http:" && isLoopbackHost(host);
+    if (target.protocol !== "https:" && !insecureOk) {
+        throw new NetDeniedError("net.insecure_url", host, `The URL must use https (${host}).`);
+    }
+    const proxy = policy.proxy;
+    const proxied = proxy !== undefined &&
+        target.protocol === "https:" &&
+        !isLoopbackHost(host) &&
+        !bypassesProxy(host, proxy.noProxy);
+    // getaddrinfo cannot be cancelled: stop waiting for it when the caller gives up
+    init.signal.throwIfAborted();
+    let onAbort = () => { };
+    const aborted = new Promise((_, reject) => {
+        onAbort = () => reject(init.signal.reason);
+        init.signal.addEventListener("abort", onAbort, { once: true });
+    });
+    let ips = [];
+    try {
+        // behind the proxy only an IP literal is checked here (no lookup); the proxy resolves names
+        if (!proxied || isIP(host) !== 0) {
+            ips = await Promise.race([resolvePublic(host, policy, opts.lookup), aborted]);
+        }
+    }
+    finally {
+        init.signal.removeEventListener("abort", onAbort);
+    }
+    const agent = proxied && proxy !== undefined
+        ? (opts.proxyDispatcherFor ?? proxyAgent)(proxy.url)
+        : (opts.dispatcherFor ?? pinnedAgent)(ips);
+    let res;
+    try {
+        res = await undiciFetch(target, {
+            ...init,
+            redirect: "manual",
+            dispatcher: agent,
+        });
+    }
+    catch (e) {
+        await agent.destroy().catch(() => { });
+        // a refusal raised while connecting (the proxy's answer to CONNECT) surfaces as itself
+        const cause = e?.cause;
+        throw cause instanceof NetDeniedError ? cause : e;
+    }
+    // close() waits for the in-flight request (the body still being read) before it closes
+    void agent.close().catch(() => { });
+    if (res.status >= 300 && res.status < 400 && res.status !== 304) {
+        await res.body?.cancel().catch(() => { });
+        throw new NetDeniedError("net.redirect", host, `${host} responded with a redirect (${res.status}); redirects are not followed.`);
+    }
+    const max = opts.maxBytes;
+    if (max !== undefined) {
+        const declared = Number(res.headers.get("content-length"));
+        if (Number.isFinite(declared) && declared > max) {
+            await res.body?.cancel().catch(() => { });
+            throw new NetBodyTooLargeError(max);
+        }
+    }
+    const raw = res.body;
+    const body = raw === null || NULL_BODY_STATUS.has(res.status)
+        ? null
+        : max === undefined
+            ? raw
+            : capBody(raw, max);
+    return new Response(body, {
+        status: res.status,
+        statusText: res.statusText,
+        headers: new Headers([...res.headers]),
+    });
+}

package/dist/orgs/directory-sync.controller.d.ts

@@ -0,0 +1,14 @@
+import { type Principal } from "../identity/principal.js";
+import type { DirectorySync } from "./directory-sync.js";
+import { type OrgContext } from "./org.guard.js";
+/**
+ * Manual directory sync (`/api/v1/orgs/:orgId/extensions/:extension/directory/sync`): it adds and
+ * removes members, so only an admin and only a human may start it.
+ */
+export declare class DirectorySyncController {
+    private readonly directory;
+    constructor(directory: DirectorySync);
+    sync(principal: Principal, org: OrgContext, extension: string): Promise<{
+        jobId: string;
+    }>;
+}

package/dist/orgs/directory-sync.controller.js

@@ -0,0 +1,40 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Controller, HttpCode, Inject, Param, Post } from "@nestjs/common";
+import { DIRECTORY_SYNC } from "../http/tokens.js";
+import { CurrentPrincipal, patTokenId, requireUser, } from "../identity/principal.js";
+import { CurrentOrg, OrgAction } from "./org.guard.js";
+/**
+ * Manual directory sync (`/api/v1/orgs/:orgId/extensions/:extension/directory/sync`): it adds and
+ * removes members, so only an admin and only a human may start it.
+ */
+let DirectorySyncController = class DirectorySyncController {
+    directory;
+    constructor(directory) {
+        this.directory = directory;
+    }
+    async sync(principal, org, extension) {
+        const p = requireUser(principal);
+        return this.directory.request(org.orgId, extension, p.account.id, patTokenId(p));
+    }
+};
+__decorate([
+    Post("sync"),
+    HttpCode(202),
+    OrgAction("org.members.manage"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("extension"))
+], DirectorySyncController.prototype, "sync", null);
+DirectorySyncController = __decorate([
+    Controller("api/v1/orgs/:orgId/extensions/:extension/directory"),
+    __param(0, Inject(DIRECTORY_SYNC))
+], DirectorySyncController);
+export { DirectorySyncController };

package/dist/orgs/directory-sync.d.ts

@@ -0,0 +1,166 @@
+import { type Logger } from "@capybara-hq/plugin-sdk";
+import type { Redis } from "ioredis";
+import type { KernelDb } from "../db/kernel-schema.js";
+import type { ExtensionHost } from "../extensions/host.js";
+import type { OrgExtensionConfigs } from "../extensions/org-config.js";
+import type { ExternalIdentities } from "../identity/external.js";
+import type { Maintenance } from "../runtime/maintenance.js";
+import type { Offboarding } from "./offboarding.js";
+/** 每小时扫描：维护队列任务名、job scheduler id（不含 `:`）与周期。 */
+export declare const DIRECTORY_SCAN_JOB = "directory-scan";
+export declare const DIRECTORY_SCAN_SCHEDULER_ID = "directory-scan-hourly";
+export declare const DIRECTORY_SCAN_EVERY_MS = 3600000;
+/** 一次 (组织, 插件) 同步的维护任务名。 */
+export declare const DIRECTORY_SYNC_JOB = "directory-sync";
+/** 同步锁的 Redis 键前缀（键为 `<前缀><orgId>:<plugin>`，带 TTL、持有期间续租）。 */
+export declare const DIRECTORY_SYNC_LOCK_PREFIX = "capk:directory-sync:";
+/** 脏标记的保留时长（秒）：锁被占时记下，持有者跑完后取走并补一轮。 */
+export declare const DIRECTORY_SYNC_DIRTY_TTL_SECONDS = 3600;
+/** 脏标记（Redis 键）：同步进行中又有同步请求被锁挡掉。 */
+export declare const directorySyncDirtyKey: (orgId: string, plugin: string) => string;
+/**
+ * Ruling A17 大批移除保护（非手动触发）：计划移除数超过 `max(下限, 比例 × 现有通讯录成员数)`，
+ * 或列表里一个在职成员都没有而已有通讯录成员时，本轮当作不完整、不移除任何人。
+ */
+export declare const DIRECTORY_REMOVAL_GUARD_MIN = 5;
+export declare const DIRECTORY_REMOVAL_GUARD_RATIO = 0.2;
+/** 单页 `listMembers` 的时限。 */
+export declare const DIRECTORY_PAGE_TIMEOUT_MS = 60000;
+/** 一轮同步最多翻的页数：防止插件反复返回游标让任务无限长（超出按中途失败处理）。 */
+export declare const DIRECTORY_MAX_PAGES = 10000;
+/** 触发来源：每小时扫描、入站 `directory_changed` 提示、管理员手动。 */
+export type DirectorySyncTrigger = "schedule" | "changed" | "manual";
+/**
+ * 不同步的原因（陈旧任务、插件已停用 / 配置不再有效、组织已删除、另一同步在跑；`not_configured`：插件的
+ * `Directory.configured` 说这份组织配置没配好通讯录，Ruling A28，静默跳过）。
+ */
+export type DirectorySkipReason = "plugin_unavailable" | "org_not_found" | "not_enabled" | "config_invalid" | "not_configured" | "locked";
+export type DirectorySyncResult = {
+    status: "skipped";
+    reason: DirectorySkipReason;
+} | {
+    status: "synced";
+    /** 新加入的成员关系数。 */
+    added: number;
+    /** 离职处理（撤销成员关系）的人数。 */
+    removed: number;
+    /** 是该组织最后一个 owner、因而跳过的人数。 */
+    skippedLastOwner: number;
+    /** 处理失败的成员数（资料不合规、加入或离职事务失败）。 */
+    failed: number;
+    /** 通讯录返回的成员总数（含离职的）。 */
+    total: number;
+    /** 分页没有完整走完、有成员处理失败或被大批移除保护拦下：只加人，不移除任何人。 */
+    partial: boolean;
+    /** 被大批移除保护（Ruling A17）拦下。 */
+    removalBlocked: boolean;
+    /** 本轮持锁期间来过通讯录变更（Ruling A32）：不移除，由随后的补跑移除。 */
+    partialReason?: "changed_during_sync";
+};
+/** 一个 (组织, 插件) 投递目标。 */
+export interface DirectorySyncTarget {
+    orgId: string;
+    plugin: string;
+    jobId: string;
+}
+/** UTC 小时桶，如 `2026102014`（不含 `:`）。 */
+export declare function hourBucket(d?: Date): string;
+/** UTC 分钟桶，如 `202610201405`。 */
+export declare function minuteBucket(d?: Date): string;
+/**
+ * 同步任务的 job id（不含 `:`）：扫描按小时桶（`directory-sync-<org>-<plugin>-<小时桶>`）、
+ * `directory_changed` 按分钟桶去重；手动触发每次唯一，不会被同一小时的扫描任务吞掉。
+ */
+export declare function directorySyncJobId(orgId: string, plugin: string, trigger: DirectorySyncTrigger, now?: Date): string;
+export interface DirectorySyncDeps {
+    db: KernelDb;
+    redis: Redis;
+    host: Pick<ExtensionHost, "list">;
+    orgExtensionConfigs: Pick<OrgExtensionConfigs, "get">;
+    external: Pick<ExternalIdentities, "resolve">;
+    offboarding: Pick<Offboarding, "offboard" | "afterCommit">;
+    /** 给了就登记每小时扫描与同步任务（worker 角色执行）；不给时只能直接调用 `sync`。 */
+    maintenance?: Pick<Maintenance, "add" | "handle" | "schedule">;
+    log: Pick<Logger, "warn" | "info">;
+}
+/**
+ * 通讯录同步（`directory@1`）：把企业通讯录同步为组织成员。框架无关。
+ *
+ * - 维护队列每小时 `directory-scan`：给每个「插件提供 `directory@1`、在该组织启用、组织级配置满足 schema」的
+ *   (组织, 插件) 投递一次同步（job id 按小时桶去重，多副本重复扫描只跑一次）；手动与 `directory_changed` 也投递同步。
+ * - 同一 (组织, 插件) 同时只跑一个同步（Redis 锁 `capk:directory-sync:<org>:<plugin>`，持有期间续租）；
+ *   锁被占时本任务记下脏标记 `capk:directory-sync-dirty:<org>:<plugin>`（1 小时）后结束；持有者释放锁后 GETDEL
+ *   取走标记，有就投递一次 changed 同步（在跑的那一轮可能已经读过变化之前的页）。Ruling A32：移除阶段前 GET
+ *   （不取走）脏标记，有就本轮按不完整处理、不移除任何人（审计 `partialReason = changed_during_sync`），移除留给补跑。
+ *   After writing the flag, a blocked sync tries the lock once more: when the holder finished in
+ *   between (and its GETDEL found no flag), this sync clears the flag and runs itself.
+ * - Ruling A17：非手动触发的一轮，计划移除数超过 `max(5, 20% × 现有通讯录成员数)`，或列表里没有在职成员而已有
+ *   通讯录成员时，当作不完整、不移除任何人，审计 `org.directory.removal_blocked`；手动触发不受此限。
+ * - 分页 `listMembers`：在职成员按 `<插件>:<租户>` + externalId 解析外部身份（不合并既有账号、不登录、不建会话），
+ *   不是成员就加入（角色 member，`memberships.source = "directory:<插件>"`），每人一个短事务；新身份行记
+ *   `linked_via = directory`。被管理员手动移出（或本人离开）而记下通讯录排除的人不加回（Ruling A20），
+ *   直到有人手动重新加入。
+ * - **整轮分页成功走完、且没有成员处理失败**、并且移除前再次复核插件仍可同步（仍启用、配置仍有效；中途被停用或
+ *   配置变得无效则本轮按不完整处理）之后，才对「离职（active = false）或不再出现、且 source 为该通讯录」的
+ *   成员逐个走离职处理（每人一个事务：组织行锁 → 成员关系行锁 → `Offboarding.offboard`）；中途失败只加人不删人。
+ *   手动 / 邀请加入的成员（source 为空）永远不被同步移除；账号本身不停用。最后一个 owner 跳过并计数。
+ * - Ruling A28：插件实现了 `Directory.configured` 且对该组织配置返回 false（通讯录未配置，组织只用插件的别的
+ *   能力）时，扫描、`directory_changed` 与执行时的复核都静默跳过（不投递、不审计、不记警告），手动触发 409
+ *   `directory.not_configured`。
+ * - 审计 `org.directory.synced`（计数、是否不完整）。任务执行时再核对插件与配置：已停用的插件的陈旧任务什么都不做。
+ */
+export declare class DirectorySync {
+    private readonly d;
+    private readonly lock;
+    constructor(d: DirectorySyncDeps);
+    /** 插件提供的 `directory@1`；未加载或不提供时 undefined。 */
+    private provider;
+    /** The org exists, the extension provides a directory, is enabled in the org and its org config satisfies the schema (reuses the `OrgExtensionConfigs.get` validation). */
+    private eligible;
+    /**
+     * 投递一次 `directory_changed` 同步（按分钟桶去重）；返回 job id。入站 `directory_changed` 经
+     * {@link DirectorySyncScheduler} 调用这里。通讯录未配置（`Directory.configured` 返回 false，Ruling A28）时
+     * 静默不投递，返回 undefined；其他不可同步的情况照常投递，由任务执行时跳过。
+     */
+    enqueue(orgId: string, plugin: string, now?: Date): Promise<string | undefined>;
+    private addJob;
+    /**
+     * Manual trigger by an admin: re-checks `org.members.manage` live under the org row lock, then that
+     * the extension can sync (does not provide a directory -> `extension.not_found`, not enabled ->
+     * `extension.not_enabled`, config no longer valid -> `extension.config_invalid`, the extension says
+     * the directory is not configured -> `directory.not_configured`, Ruling A28), and enqueues a sync
+     * job with a unique id.
+     */
+    request(orgId: string, plugin: string, actorAccountId: string, actorTokenId?: string): Promise<{
+        jobId: string;
+    }>;
+    /**
+     * 每小时扫描：给每个可同步的 (组织, 插件) 投递一次同步（job id 按小时桶），返回投递的目标。
+     * 已存配置不再满足 schema 的跳过（记 warn）；单个投递失败记 warn、继续其他目标。
+     */
+    scan(now?: Date): Promise<DirectorySyncTarget[]>;
+    /** 执行一轮同步（维护任务的处理函数；测试可直接调用）。 */
+    sync(orgId: string, plugin: string, opts?: {
+        trigger?: DirectorySyncTrigger;
+        requestedBy?: string | undefined;
+        requestedByToken?: string | undefined;
+    }): Promise<DirectorySyncResult>;
+    /**
+     * 释放锁之后取走脏标记（GETDEL，只有一个副本取得到）；有标记就投递一次 changed 同步。
+     * job id 每次唯一（`…-rerun-<uuid>`）：不能被刚刚被挡掉的同一分钟的 changed 任务 id 吞掉。失败只记 warn。
+     */
+    private rerunIfDirty;
+    private run;
+    /**
+     * 一个在职成员：解析外部身份（不合并、不登录，新身份行 `linked_via = directory`），不是成员就以 member 加入
+     * （source = 本通讯录）；此人在该组织有本通讯录的排除（被手动移出 / 本人离开过）时不加入。
+     * 组织行锁内完成（与移出成员同一把锁、与移出时写排除串行），组织已删除 → {@link OrgGone}。
+     */
+    private addMember;
+    /**
+     * 一个离职者：独立事务内先锁组织行、再锁其成员关系行（与 `switchCurrentOrg` / 移出成员同一顺序），
+     * 确认仍是本通讯录加入的，再走 `Offboarding.offboard`（吊销会话与令牌、删个人凭据、转交 agent 都在这个事务里）。
+     * 最后一个 owner → 回滚并返回 `last_owner`；期间已被移除或不再是本通讯录加入的 → `gone`。
+     */
+    private offboardOne;
+}