userly-acl

userly-acl нь Userly resource server/backend дээр authorization snapshot ашиглан role, permission, policy check хийх helper package.

Энэ package OAuth/OIDC login SDK биш. Login redirect, Authorization Code + PKCE, refresh token rotation, browser session/cookie management хийхгүй.

Release 1 scope

• Access token claim болон authorization snapshot consistency check.
• hasRole() болон can() authorization evaluator.
• System Role -> Permission direct check.
• Tenant Top Role -> Child Role -> Permission -> Policy expansion.
• Explicit system + resource болон tenant + tenant_id + resource scope consistency.
• Built-in policy guard evaluator: time_window, ip_allowlist, ip_denylist, owner_only.
• Snapshot fetch helper, Userly-ACL-Version header injection, ETag support.
• authz.snapshot_changed, authz.subject_changed webhook payload parser.

Snapshot-г заавал network-оор fetch хийх албагүй. sysop-server, tenant-server зэрэг first-party server snapshot data-г өөрөө build/fill хийгээд evaluator-д өгч болно.

Install

npm install userly-acl

Snapshot fetch

fetchAuthorizationSnapshot() нь /authz/snapshot endpoint-оос snapshot авна. Client authentication буюу private_key_jwt assertion үүсгэхийг энэ package хийхгүй. Caller нь бэлэн Authorization header дамжуулна.

import { fetchAuthorizationSnapshot } from "userly-acl";

const result = await fetchAuthorizationSnapshot({
    baseUrl: "https://auth.example.mn",
    scope: "tenant",
    tenantId: "tenant-id",
    resource: "crm-api",
    etag: previousEtag,
    authorizationHeader: async () => `Bearer ${await createClientAssertion()}`
});

if (!result.notModified && result.snapshot) {
    cache.set("crm-api:tenant-id", {
        etag: result.etag,
        snapshot: result.snapshot
    });
}

ACL check

import { createAclEvaluator } from "userly-acl";

const acl = createAclEvaluator(snapshot);
const decision = acl.can({
    token: accessTokenClaims,
    permission: "customer.read",
    context: {
        ipAddress: requestIp
    }
});

if (!decision.allowed) {
    throw new Error(decision.code);
}

hasRole() нь access token дээрх role claim тухайн snapshot дээр байгаа эсэхийг шалгана. can() нь role expansion, permission, policy guard бүгдийг шалгана.

Webhook

Userly дээр ACL snapshot эсвэл subject state өөрчлөгдвөл resource server webhook авч cache refresh хийж болно.

import { parseAuthzWebhookEvent } from "userly-acl";

const event = parseAuthzWebhookEvent(requestBody);

if (event.event === "authz.snapshot_changed") {
    await refreshSnapshot(event.scope, event.resource, event.tenantId);
}

if (event.event === "authz.subject_changed") {
    await refreshSubjectState(event.userId, event.scope, event.tenantId);
}

Version compatibility

Package нь snapshot request бүр дээр Userly-ACL-Version header илгээнэ. Default утга нь package version-тэй ижил байна.

Release 1 publish эхлэх version: 0.1.0.

Publish checklist

npm run typecheck -w userly-acl
npm run test -w userly-acl
npm pack --dry-run -w userly-acl
npm publish -w userly-acl

npm pack --dry-run output дээр зөвхөн dist, README.md, package.json орсон байх ёстой.