@knowttl/mg-axi 0.1.0

package/dist/profiles.js

@@ -0,0 +1,139 @@
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { AxiError } from "axi-sdk-js";
+const guid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const namePattern = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/;
+const object = (value) => !!value && typeof value === "object" && !Array.isArray(value);
+const exact = (value, keys) => Object.keys(value).every(key => keys.includes(key));
+function invalid(message) {
+    throw new AxiError(message, "VALIDATION_ERROR", ["mg-axi profile create --help", "Correct the version-1 profile configuration; no automatic migration is performed"]);
+}
+const thumbprint = /^[0-9a-f]{40}$/i;
+const sharedKeys = ["mode", "tenantId", "clientId", "cloud", "enabledPacks", "preview", "sensitiveAreas", "credentialRef", "allowDeviceCode", "writes"];
+const MAX_WRITE_OPERATIONS = 64;
+const MAX_WRITE_OPERATION_LENGTH = 256;
+function validateWrites(value) {
+    if (value === undefined)
+        return undefined;
+    if (!object(value) || !exact(value, ["allowWrites", "operations"]) || typeof value.allowWrites !== "boolean" ||
+        !Array.isArray(value.operations) || value.operations.length === 0 || value.operations.length > MAX_WRITE_OPERATIONS ||
+        value.operations.some(entry => typeof entry !== "string" || !entry.length || entry.length > MAX_WRITE_OPERATION_LENGTH)) {
+        invalid("Invalid write policy; hand-edit a writes object with boolean allowWrites and a nonempty operations array of nonempty operation names");
+    }
+    return Object.freeze({ allowWrites: value.allowWrites, operations: Object.freeze([...value.operations]) });
+}
+const sharedIdentity = (value) => value.cloud === "commercial" && typeof value.tenantId === "string" && guid.test(value.tenantId) &&
+    typeof value.clientId === "string" && guid.test(value.clientId) && typeof value.preview === "boolean" &&
+    Array.isArray(value.enabledPacks) && value.enabledPacks.every(pack => pack === "entra") && new Set(value.enabledPacks).size === value.enabledPacks.length &&
+    Array.isArray(value.sensitiveAreas) && value.sensitiveAreas.length === 0;
+export function validateDelegatedProfile(value) {
+    if (!object(value) || !exact(value, sharedKeys) || value.mode !== "delegated" || !sharedIdentity(value) || typeof value.allowDeviceCode !== "boolean" ||
+        !object(value.credentialRef) || !exact(value.credentialRef, ["provider", "key"]) || value.credentialRef.provider !== "os-or-session" ||
+        typeof value.credentialRef.key !== "string" || !guid.test(value.credentialRef.key))
+        invalid("Invalid delegated profile; explicit tenant/client IDs and commercial cloud are required, with credentials only by reference");
+    const profile = value;
+    const writes = validateWrites(value.writes);
+    return Object.freeze({ mode: "delegated", tenantId: profile.tenantId, clientId: profile.clientId, cloud: "commercial", preview: profile.preview,
+        allowDeviceCode: profile.allowDeviceCode, enabledPacks: Object.freeze([...profile.enabledPacks]), sensitiveAreas: Object.freeze([]),
+        credentialRef: Object.freeze({ provider: "os-or-session", key: profile.credentialRef.key }), ...(writes === undefined ? {} : { writes }) });
+}
+export function validateApplicationProfile(value) {
+    if (!object(value) || !exact(value, sharedKeys) || value.mode !== "application" || !sharedIdentity(value) || value.allowDeviceCode !== false ||
+        !object(value.credentialRef))
+        invalid("Invalid application profile; explicit tenant/client IDs and commercial cloud are required, with credentials only by reference");
+    const profile = value;
+    const ref = profile.credentialRef;
+    const writes = validateWrites(value.writes);
+    const writeFields = writes === undefined ? {} : { writes };
+    if (ref.provider === "certificate" && exact(ref, ["provider", "key", "thumbprint"]) && typeof ref.key === "string" && guid.test(ref.key) &&
+        typeof ref.thumbprint === "string" && thumbprint.test(ref.thumbprint)) {
+        return Object.freeze({ mode: "application", tenantId: profile.tenantId, clientId: profile.clientId, cloud: "commercial",
+            preview: profile.preview, allowDeviceCode: false, enabledPacks: Object.freeze([...profile.enabledPacks]), sensitiveAreas: Object.freeze([]),
+            credentialRef: Object.freeze({ provider: "certificate", key: ref.key, thumbprint: ref.thumbprint.toLowerCase() }), ...writeFields });
+    }
+    if (ref.provider === "federated" && exact(ref, ["provider", "key"]) && typeof ref.key === "string" && guid.test(ref.key)) {
+        return Object.freeze({ mode: "application", tenantId: profile.tenantId, clientId: profile.clientId, cloud: "commercial",
+            preview: profile.preview, allowDeviceCode: false, enabledPacks: Object.freeze([...profile.enabledPacks]), sensitiveAreas: Object.freeze([]),
+            credentialRef: Object.freeze({ provider: "federated", key: ref.key }), ...writeFields });
+    }
+    invalid("Invalid application profile; credentialRef must be a certificate or federated reference, never inlined key material");
+}
+export function validateProfile(value) {
+    if (!!value && typeof value === "object" && !Array.isArray(value) && value.mode === "application")
+        return validateApplicationProfile(value);
+    return validateDelegatedProfile(value);
+}
+export class Profiles {
+    path;
+    constructor(path = process.env.MG_AXI_CONFIG ?? join(homedir(), ".mg-axi", "config.json")) {
+        this.path = path;
+    }
+    load() {
+        let value;
+        try {
+            value = JSON.parse(readFileSync(this.path, "utf8"));
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return { version: 1, profiles: {} };
+            invalid("Unable to read profile configuration; check the file permissions and version-1 JSON schema");
+        }
+        if (!object(value) || value.version !== 1 || !exact(value, ["version", "defaultProfile", "profiles"]) || !object(value.profiles))
+            invalid("Unsupported profile configuration; explicitly migrate to version 1");
+        const profiles = Object.create(null);
+        for (const [name, profile] of Object.entries(value.profiles)) {
+            if (!namePattern.test(name))
+                invalid("Invalid profile name");
+            profiles[name] = validateProfile(profile);
+        }
+        if (value.defaultProfile !== undefined && (typeof value.defaultProfile !== "string" || !Object.hasOwn(profiles, value.defaultProfile)))
+            invalid("Default profile does not exist");
+        if (new Set(Object.values(profiles).map(profile => profile.credentialRef.key)).size !== Object.keys(profiles).length)
+            invalid("Each profile must have a separate credential reference");
+        return { version: 1, profiles, defaultProfile: value.defaultProfile };
+    }
+    list() { return Object.entries(this.load().profiles).map(([name, profile]) => ({ name, mode: profile.mode, tenant: profile.tenantId, cloud: profile.cloud })); }
+    resolve(name) {
+        const config = this.load();
+        const selected = name ?? config.defaultProfile;
+        if (!selected || !Object.hasOwn(config.profiles, selected))
+            throw new AxiError("No configured profile selected", "AUTH_REQUIRED", ["mg-axi profile list", "mg-axi profile create --help"]);
+        return { name: selected, profile: config.profiles[selected] };
+    }
+    create(name, tenantId, clientId, cloud, allowDeviceCode, application) {
+        if (!namePattern.test(name))
+            invalid("Profile name must contain only letters, digits, underscores or hyphens");
+        const certificate = application?.certificateThumbprint;
+        const federated = application?.federated ?? false;
+        if (application && (certificate !== undefined && (typeof certificate !== "string" || !/^[0-9a-f]{40}$/i.test(certificate))))
+            invalid("Application certificate profiles name a 40-hex-digit thumbprint; the private key stays in protected storage");
+        if (application && ((certificate === undefined) === !federated))
+            invalid("Application profiles use exactly one credential: --certificate-thumbprint or --federated");
+        if (application && allowDeviceCode)
+            invalid("Application profiles never use device code; it is a delegated login method");
+        const profile = application
+            ? validateApplicationProfile({ mode: "application", tenantId, clientId, cloud, enabledPacks: ["entra"], preview: false, sensitiveAreas: [],
+                credentialRef: certificate === undefined ? { provider: "federated", key: randomUUID() } : { provider: "certificate", key: randomUUID(), thumbprint: certificate }, allowDeviceCode: false })
+            : validateDelegatedProfile({ mode: "delegated", tenantId, clientId, cloud, enabledPacks: ["entra"], preview: false, sensitiveAreas: [], credentialRef: { provider: "os-or-session", key: randomUUID() }, allowDeviceCode });
+        const config = this.load();
+        if (Object.hasOwn(config.profiles, name))
+            invalid("Profile already exists; creation never replaces identity");
+        config.profiles[name] = profile;
+        config.defaultProfile ??= name;
+        mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 });
+        const temporary = `${this.path}.${randomUUID()}.tmp`;
+        try {
+            writeFileSync(temporary, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600, flag: "wx" });
+            renameSync(temporary, this.path);
+        }
+        catch {
+            throw new AxiError("Unable to save profile configuration", "CONFIG_ERROR", ["Check configuration directory permissions"]);
+        }
+        finally {
+            rmSync(temporary, { force: true });
+        }
+        return { name, mode: profile.mode, tenant: profile.tenantId, cloud: profile.cloud };
+    }
+}

package/dist/setup.js

@@ -0,0 +1,116 @@
+import { LEAVES } from "./catalogue.js";
+// PACK-01: explicit release setup guidance. The setup view is offline: it
+// reads the selected configuration file, describes installation and the
+// supported Entra read surface, and points at the generated skill and
+// capability report. It writes nothing, signs in nowhere and installs no
+// hooks; ordinary commands never gain installation side effects. See
+// README.md for the release notes and skills/mg-axi/SKILL.md for the
+// installable skill.
+// EXT-01b document gate (D2): the capability prose lists the shipped read
+// families, driven from the catalogue in catalogue order, so a merged read
+// slice extends the sentence without touching this template. Paths outside
+// the known prefixes fall back to their two-segment leaf key and are never
+// silently omitted from the list.
+const READ_FAMILY_PREFIXES = [
+    ["entra user", "user"],
+    ["entra registration", "registration"],
+    ["entra group", "group"],
+    ["entra directory-role", "directory-role/PIM"],
+    ["entra role-assignment", "directory-role/PIM"],
+    ["entra pim", "directory-role/PIM"],
+    ["entra device", "device"],
+    ["entra administrative-unit", "administrative-unit"],
+    ["entra organization", "organization and branding"],
+    ["entra domain", "domain and domain DNS"],
+    ["entra domain-dns-record", "domain and domain DNS"],
+    ["entra certificate-auth-pki", "certificate authentication"],
+    ["entra certificate-authority", "certificate authentication"],
+    ["entra subscription", "commercial subscriptions"],
+    ["entra on-premises-synchronization", "on-premises synchronization"],
+    ["entra agreement", "terms-of-use agreements and acceptances"],
+    ["entra agreement-acceptance", "terms-of-use agreements and acceptances"],
+    ["entra directory-object", "directory objects"],
+    ["entra deleted-user", "deleted directory items"],
+    ["entra deleted-group", "deleted directory items"],
+    ["entra deleted-application", "deleted directory items"],
+    ["entra deleted-service-principal", "deleted directory items"],
+    ["entra deleted-administrative-unit", "deleted directory items"],
+    ["entra deleted-item", "deleted directory items"],
+    ["entra contact", "organizational contacts"],
+    ["entra group-lifecycle-policy", "group lifecycle policies"],
+    ["entra group-setting-template", "group setting templates"],
+    ["entra attribute-set", "attribute sets and custom security attributes"],
+    ["entra custom-security-attribute-definition", "attribute sets and custom security attributes"],
+    ["entra allowed-value", "attribute sets and custom security attributes"],
+    ["entra contract", "partner contracts"],
+    ["entra delegated-admin-customer", "delegated administration"],
+    ["entra delegated-admin-relationship", "delegated administration"],
+    ["entra multi-tenant-organization", "multi-tenant organization"],
+    ["entra tenant-information", "tenant information"],
+    ["entra sign-in", "sign-in/directory-audit"],
+    ["entra directory-audit", "sign-in/directory-audit"],
+    ["entra application", "application/service-principal and consent grants"],
+    ["entra service-principal", "application/service-principal and consent grants"],
+    ["entra risky-user", "risk"],
+    ["entra risk-detection", "risk"],
+    ["entra conditional-access", "Conditional Access"],
+    ["entra identity-provider", "identity-provider"],
+    ["entra federation-configuration", "federation configurations"],
+    ["entra data-policy-operation", "data policy operations"],
+    ["entra access-review", "access-review"],
+    ["entra entitlement catalog", "entitlement catalogs and access packages"],
+    ["entra entitlement access-package", "entitlement catalogs and access packages"],
+    ["entra entitlement assignment", "entitlement assignments and requests"],
+    ["entra entitlement assignment-request", "entitlement assignments and requests"],
+    ["entra entitlement assignment-policy", "entitlement catalogs and access packages"],
+    ["entra entitlement resource-role-scope", "entitlement catalogs and access packages"],
+    ["entra lifecycle", "lifecycle workflows"],
+];
+function shippedReadFamilies() {
+    const seen = [];
+    for (const leaf of LEAVES) {
+        if (leaf.operation === undefined || !leaf.operation.startsWith("GET:"))
+            continue;
+        const match = READ_FAMILY_PREFIXES.find(([prefix]) => leaf.path === prefix || leaf.path.startsWith(`${prefix} `));
+        const label = match ? match[1] : leaf.path.split(" ").slice(0, 2).join(" ");
+        if (!seen.includes(label))
+            seen.push(label);
+    }
+    return seen;
+}
+export function setupView(store) {
+    const families = shippedReadFamilies();
+    const items = store.list();
+    const implemented = LEAVES.map(leaf => leaf.path);
+    const reads = LEAVES.filter(leaf => (leaf.operation !== undefined && leaf.operation.startsWith("GET:")) || leaf.path === "api get" || leaf.path === "doctor").length;
+    const writes = LEAVES.filter(leaf => leaf.operation !== undefined && !leaf.operation.startsWith("GET:")).length;
+    return {
+        command: "mg-axi setup",
+        config: store.path,
+        state: items.length ? "configured" : "unconfigured",
+        profiles: items.length
+            ? items.map(item => ({ name: item.name, mode: item.mode }))
+            : "0 profiles configured",
+        installation: [
+            "corepack pnpm install --frozen-lockfile --ignore-scripts --config.confirm-modules-purge=false",
+            "corepack pnpm build",
+            "node dist/bin/mg-axi.js --version",
+        ],
+        guidance: [
+            `Hand-edit ${store.path} or set MG_AXI_CONFIG to a separate configuration file; secrets stay in protected storage references, never in argv or config`,
+            "node dist/bin/mg-axi.js profile create --name soc --tenant <tenant-id> --client <client-id> --cloud commercial",
+            "node dist/bin/mg-axi.js login --profile soc --scopes https://graph.microsoft.com/User.Read.All",
+            "node dist/bin/mg-axi.js doctor",
+        ],
+        capabilities: {
+            implemented,
+            reads,
+            writes,
+            local: implemented.length - reads - writes,
+            api: `Entra ${families.slice(0, -1).join(", ")} and ${families.at(-1)} reads plus reviewed raw api get, one gated group-membership write, one gated account enable/disable write, one gated session-revocation write and one gated risky-user dismissal write; every other operation is scheduled, blocked, deprecated or excluded`,
+            report: "docs/coverage.md",
+        },
+        integration: "Install skills/mg-axi/SKILL.md explicitly through your agent's skill installation mechanism; setup only shows guidance and installs no skills or hooks",
+        help: ["node dist/bin/mg-axi.js doctor", "node dist/bin/mg-axi.js entra user list --help", "node dist/bin/mg-axi.js api get --help"],
+    };
+}

package/dist/version.js

@@ -0,0 +1,2 @@
+import { readFileSync } from "node:fs";
+export const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;