@krak-stack/auth 0.1.60 → 0.1.62

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,86 +1,66 @@
1
1
  # @krak-stack/auth
2
2
 
3
- Effect schemas and typed HttpApi clients for KrakStack Auth.
3
+ Typed Effect contracts, server authentication middleware, project authorization primitives, and React authentication components for Krakstack Auth.
4
4
 
5
5
  ## Install
6
6
 
7
- ```sh
7
+ ```bash
8
8
  bun add @krak-stack/auth effect
9
9
  ```
10
10
 
11
- ## Environment
11
+ Choose a narrow package subpath for the runtime boundary:
12
12
 
13
- - `VITE_KRAKSTACK_AUTH_URL` - KrakStack Auth origin
14
- - `KRAKSTACK_AUTH_SERVICE_API_KEY` - service API key for server clients
13
+ | Entry point | Purpose |
14
+ | -------------------------------- | --------------------------------------------------------------------- |
15
+ | `@krak-stack/auth/server` | Proxy, `AuthMiddleware`, `AuthService`, `ActorRequired`, and policies |
16
+ | `@krak-stack/auth/components` | React provider, forms, account controls, and UI permission helpers |
17
+ | `@krak-stack/auth/access` | Typed project access definitions |
18
+ | `@krak-stack/auth/access/matrix` | Generated permission matrix |
19
+ | `@krak-stack/auth/api` | Combined Effect HttpApi contracts |
20
+ | `@krak-stack/auth/schema` | Shared schemas |
21
+ | `@krak-stack/auth/admin` | Administrative API contract |
22
+ | `@krak-stack/auth/extra` | Browser-facing extra API contract |
15
23
 
16
- ## Auth Client
24
+ The complete export map is defined in `package.json` and documented at [auth.krakstack.net/en/docs/sdk](https://auth.krakstack.net/en/docs/sdk).
17
25
 
18
- Better Auth:
26
+ ## Server Configuration
19
27
 
20
- - `getSession({ payload: {} })` - returns the current Better Auth session and user.
28
+ Server clients use:
21
29
 
22
- Users:
30
+ ```env
31
+ KRAKSTACK_AUTH_URL=https://auth.example.com
32
+ KRAKSTACK_AUTH_SERVICE_API_KEY=server_only_secret
33
+ ```
23
34
 
24
- - `server.listUsersByIds({ query: { ids } })` - returns matching users and missing IDs for a comma-separated ID list.
25
- - `server.getUser({ params: { id } })` - returns one user by ID.
35
+ `AuthClientConfig` accepts explicit `baseUrl` and redacted `apiKey` overrides. Never expose the service key through a `VITE_*` variable.
26
36
 
27
- Organizations:
37
+ ```ts
38
+ import { AuthService } from "@krak-stack/auth/server";
39
+ import { Effect } from "effect";
28
40
 
29
- - `server.listOrganizations({ query: { ids } })` - returns matching organizations and missing IDs for a comma-separated ID list.
30
- - `server.listOrganizations({ query: { userId } })` - returns organizations for one user.
31
- - `server.getOrganization({ params: { id } })` - returns one organization by ID.
32
- - `server.getUserActiveOrganization({ params: { userId } })` - returns the active organization ID for one user.
33
- - `extra.presign({ payload })` - returns a presigned organization logo upload URL.
41
+ const program = Effect.gen(function* () {
42
+ const auth = yield* AuthService;
43
+ return yield* auth.requireUserOrganization();
44
+ });
45
+ ```
34
46
 
35
- Members:
47
+ Use `AuthMiddleware.layer()` to provide request headers and configuration in an Effect HttpApi application. See the [middleware guide](https://auth.krakstack.net/en/docs/middleware).
36
48
 
37
- - `server.getActiveMember({ params: { organizationId, userId } })` - returns one user's membership and role in an organization.
38
- - `server.listOrganizationMembers({ params: { organizationId } })` - returns organization members with user contact details.
49
+ ## React Components
39
50
 
40
- ```ts
41
- import { Effect } from "effect";
42
- import { AuthClient } from "@krak-stack/auth";
43
-
44
- const users = await Effect.runPromise(
45
- Effect.gen(function* () {
46
- const auth = yield* AuthClient;
47
- return yield* auth.server.listUsersByIds({
48
- query: { ids: "user_1,user_2" },
49
- });
50
- }).pipe(Effect.provide(AuthClient.layer)),
51
- );
52
-
53
- const organizations = await Effect.runPromise(
54
- Effect.gen(function* () {
55
- const auth = yield* AuthClient;
56
- return yield* auth.server.listOrganizations({
57
- query: { userId: "user_1" },
58
- });
59
- }).pipe(Effect.provide(AuthClient.layer)),
60
- );
61
- ```
51
+ The current emitted component bundle expects Krakstack/shadcn UI aliases and additional consumer runtime packages. Validate the packed package in the target application before adopting the UI surface. The server-only entry points have a smaller integration boundary.
52
+
53
+ When components are configured, register their Tailwind source:
62
54
 
63
- The extra subpath also exports `ExtraApiClient` for Atom-based browser state.
64
-
65
- ## Components
66
-
67
- ```tsx
68
- import { OrganizationSwitcher, UserButton } from "@krak-stack/auth";
69
- import { DropdownMenuItem } from "@/components/ui/dropdown-menu";
70
-
71
- <OrganizationSwitcher
72
- allowedOrganizationIds={["organization-id"]}
73
- features={{
74
- organizationCreation: false,
75
- organizationSwitching: false,
76
- userInvitations: false,
77
- }}
78
- menuActions={
79
- <DropdownMenuItem render={<a href="/organization" />}>
80
- Dashboard
81
- </DropdownMenuItem>
82
- }
83
- side="bottom"
84
- />
85
- <UserButton signOutRedirect="/" side="bottom" />
55
+ ```css
56
+ @import "tailwindcss";
57
+ @import "@krak-stack/auth/tailwind.css";
86
58
  ```
59
+
60
+ See [React components and CSS](https://auth.krakstack.net/en/docs/components) for the provider and component requirements.
61
+
62
+ ## Authorization
63
+
64
+ Define project permissions with `defineProjectAccess`, resolve actors with `ActorRequired`, and enforce backend policies with `withPolicy`. Frontend permission helpers control presentation only.
65
+
66
+ See the [RBAC guide](https://auth.krakstack.net/en/docs/rbac).
package/dist/access.d.ts CHANGED
@@ -15,9 +15,6 @@ export type ApiKeyOwner = {
15
15
  } | {
16
16
  readonly type: "organization";
17
17
  readonly organizationId: string;
18
- } | {
19
- readonly type: "service";
20
- readonly serviceId: string;
21
18
  };
22
19
  export type ApiKeyActor = {
23
20
  readonly type: "apiKey";
@@ -51,7 +48,6 @@ export type ProjectAccessDefinition<Project extends string = string, Action exte
51
48
  readonly apiKeys: {
52
49
  readonly user: ReadonlyArray<Action>;
53
50
  readonly organization: ReadonlyArray<Action>;
54
- readonly service: ReadonlyArray<Action>;
55
51
  };
56
52
  readonly qualify: (action: Action) => ProjectPermission<Project, Action>;
57
53
  readonly permission: (action: Action) => Policy;
@@ -63,9 +59,10 @@ export type ProjectAccessDefinition<Project extends string = string, Action exte
63
59
  }) => ReadonlySet<ProjectPermission<Project, Action>>;
64
60
  readonly decodeGrant: (input: unknown) => Effect.Effect<ReadonlySet<ProjectPermission<Project, Action>>, Schema.SchemaError>;
65
61
  readonly encodeGrant: (actions: ReadonlyArray<Action>) => ApiKeyPermissionGrant;
66
- readonly userApiKeyPermissions: ApiKeyPermissionGrant;
67
- readonly organizationApiKeyPermissions: ApiKeyPermissionGrant;
68
- readonly serviceApiKeyPermissions: ApiKeyPermissionGrant;
62
+ readonly apiKeyPermissions: {
63
+ readonly user: ApiKeyPermissionGrant;
64
+ readonly organization: ApiKeyPermissionGrant;
65
+ };
69
66
  readonly actorForUser: (input: {
70
67
  readonly userId: string;
71
68
  readonly organizationId: string | null;
@@ -77,12 +74,26 @@ export type ProjectAccessDefinition<Project extends string = string, Action exte
77
74
  readonly grant: ApiKeyPermissionGrant | null | undefined;
78
75
  }) => CurrentActor;
79
76
  };
80
- export type ProjectAccessCatalog = {
77
+ export type ProjectAccessCatalog = Pick<ProjectAccessDefinition, "project" | "roles" | "apiKeyPermissions">;
78
+ export type ProjectAccessLabelCatalog = {
79
+ readonly project: string;
80
+ readonly roles: Readonly<Record<string, string | undefined>>;
81
+ readonly permissions: Readonly<Record<string, {
82
+ readonly label: string;
83
+ readonly actions: Readonly<Record<string, string>>;
84
+ }>>;
85
+ };
86
+ type PermissionResource<Action extends string> = Action extends `${infer Resource}:${string}` ? Resource : Action;
87
+ type PermissionAction<Action extends string, Resource extends string> = Action extends `${Resource}:${infer Value}` ? Value : never;
88
+ export type ProjectAccessLabels<Action extends string = string, Role extends string = string> = {
81
89
  readonly project: string;
82
- readonly roles: Readonly<Record<string, ReadonlyArray<string> | undefined>>;
83
- readonly userApiKeyPermissions: ApiKeyPermissionGrant;
84
- readonly organizationApiKeyPermissions: ApiKeyPermissionGrant;
85
- readonly serviceApiKeyPermissions: ApiKeyPermissionGrant;
90
+ readonly roles: Readonly<Partial<Record<Role, string>>>;
91
+ readonly permissions: {
92
+ readonly [Resource in PermissionResource<Action>]: {
93
+ readonly label: string;
94
+ readonly actions: Readonly<Record<PermissionAction<Action, Resource>, string>>;
95
+ };
96
+ };
86
97
  };
87
98
  export type ProjectAccessConfig<Project extends string, Permissions extends ReadonlyArray<string>> = {
88
99
  readonly project: Project;
@@ -91,8 +102,11 @@ export type ProjectAccessConfig<Project extends string, Permissions extends Read
91
102
  readonly apiKeys?: {
92
103
  readonly user?: ReadonlyArray<Permissions[number]>;
93
104
  readonly organization?: ReadonlyArray<Permissions[number]>;
94
- readonly service?: ReadonlyArray<Permissions[number]>;
95
105
  };
96
106
  };
97
107
  export declare const defineProjectAccess: <const Project extends string, const Permissions extends ReadonlyArray<string>>(config: ProjectAccessConfig<Project, Permissions>) => ProjectAccessDefinition<Project, Permissions[number]>;
108
+ export declare const defineProjectAccessLabels: <const Action extends string, const Role extends string>(_access: {
109
+ readonly actions: ReadonlyArray<Action>;
110
+ readonly roles: Readonly<Record<Role, ReadonlyArray<Action> | undefined>>;
111
+ }, labels: ProjectAccessLabels<Action, Role>) => ProjectAccessLabels<Action, Role>;
98
112
  export {};
package/dist/access.js CHANGED
@@ -54,7 +54,6 @@ export const defineProjectAccess = (config) => {
54
54
  });
55
55
  const userApiKeyActions = (config.apiKeys?.user ?? []).filter((action) => allowedActions.has(action));
56
56
  const organizationApiKeyActions = (config.apiKeys?.organization ?? []).filter((action) => allowedActions.has(action));
57
- const serviceApiKeyActions = (config.apiKeys?.service ?? []).filter((action) => allowedActions.has(action));
58
57
  const actorForUser = (input) => {
59
58
  const roles = roleList(input.roles);
60
59
  return {
@@ -76,18 +75,15 @@ export const defineProjectAccess = (config) => {
76
75
  return intersection(intersection(permissionsForRoles(input.owner.roles), permissionsForActions(userApiKeyActions)), keyPermissions);
77
76
  case "organization":
78
77
  return intersection(permissionsForActions(organizationApiKeyActions), keyPermissions);
79
- case "service":
80
- return intersection(permissionsForActions(serviceApiKeyActions), keyPermissions);
81
78
  }
82
79
  })();
83
- const organizationId = input.owner.type === "service" ? null : input.owner.organizationId;
84
80
  return {
85
81
  actor: {
86
82
  type: "apiKey",
87
83
  apiKeyId: input.apiKeyId,
88
84
  owner: input.owner,
89
85
  },
90
- organizationId,
86
+ organizationId: input.owner.organizationId,
91
87
  permissions,
92
88
  };
93
89
  };
@@ -98,7 +94,6 @@ export const defineProjectAccess = (config) => {
98
94
  apiKeys: {
99
95
  user: userApiKeyActions,
100
96
  organization: organizationApiKeyActions,
101
- service: serviceApiKeyActions,
102
97
  },
103
98
  qualify,
104
99
  permission: (action) => permission(qualify(action)),
@@ -107,10 +102,12 @@ export const defineProjectAccess = (config) => {
107
102
  permissionsForUserKey: ({ grant, roles }) => intersection(intersection(permissionsForRoles(roles), permissionsForActions(userApiKeyActions)), permissionsForGrant(grant)),
108
103
  decodeGrant: (input) => Schema.decodeUnknownEffect(ApiKeyPermissionGrant)(input).pipe(Effect.map(permissionsForGrant)),
109
104
  encodeGrant,
110
- userApiKeyPermissions: encodeGrant(userApiKeyActions),
111
- organizationApiKeyPermissions: encodeGrant(organizationApiKeyActions),
112
- serviceApiKeyPermissions: encodeGrant(serviceApiKeyActions),
105
+ apiKeyPermissions: {
106
+ user: encodeGrant(userApiKeyActions),
107
+ organization: encodeGrant(organizationApiKeyActions),
108
+ },
113
109
  actorForUser,
114
110
  actorForApiKey,
115
111
  };
116
112
  };
113
+ export const defineProjectAccessLabels = (_access, labels) => labels;