@auth-craft/tenant-access-control

⚠️ Experimental / Internal Use

This package is published for convenience only.

• No stability guarantee
• Breaking changes may happen at any time
• No documentation
• No support

Use at your own risk.

Tenant Access Control SDK for managing user permissions within tenants.

Installation

npm install @auth-craft/tenant-access-control @auth-craft/tenant-access-control-dynamodb

Quick Start

import {
  createTenantAccessSDK,
  type TenantId,
  type UserId,
} from '@auth-craft/tenant-access-control';
import { createTenantAccessDynamoDBPlugin } from '@auth-craft/tenant-access-control-dynamodb';

// 1. Create DynamoDB plugin
const plugin = createTenantAccessDynamoDBPlugin({
  tableName: 'your-auth-table',
});

// 2. Create SDK
const tenantAccess = createTenantAccessSDK(plugin);

// 3. Use SDK
const member = await tenantAccess.getMember({
  tenantId: 'org-abc' as TenantId,
  userId: 'user-123' as UserId,
});

API

createTenantAccessSDK(deps)

Creates a TenantAccessSDK instance.

Parameters:

• deps.tenantMemberRepository - TenantMemberRepository implementation
• deps.sessionRepository - SessionRepository implementation

Returns: TenantAccessSDK

SDK Methods

getMember(input)

Get member info (limited fields: status, role, permMask).

const result = await sdk.getMember({
  tenantId: 'org-abc' as TenantId,
  userId: 'user-123' as UserId,
});

if (result.isOkWithData()) {
  console.log(result.data);
  // { status: 'active', role: 'editor', permMask: 12 }
}

addMember(input)

Add a user to tenant.

const result = await sdk.addMember({
  tenantId: 'org-abc' as TenantId,
  userId: 'user-456' as UserId,
  status: 'active',
  role: 'editor',      // optional
  permMask: 0b1100,    // optional
});

updateMember(input)

Update member status, role, or permMask.

const result = await sdk.updateMember({
  tenantId: 'org-abc' as TenantId,
  userId: 'user-456' as UserId,
  status: 'suspended', // optional
  role: 'viewer',      // optional
  permMask: 0b0100,    // optional
});

removeMember(input)

Remove member from tenant.

const result = await sdk.removeMember({
  tenantId: 'org-abc' as TenantId,
  userId: 'user-456' as UserId,
});

revokeSessionsByTenant(input)

Revoke all sessions for a user in specific tenant.

const result = await sdk.revokeSessionsByTenant({
  tenantId: 'org-abc' as TenantId,
  userId: 'user-456' as UserId,
});

if (result.isOkWithData()) {
  console.log(`Revoked ${result.data} sessions`);
}

Types

Branded Types

type TenantId = string & { readonly __brand: 'TenantId' };
type UserId = string & { readonly __brand: 'UserId' };
type SessionId = string & { readonly __brand: 'SessionId' };

TenantMemberStatus

type TenantMemberStatus = 'invited' | 'active' | 'suspended' | 'removed';

TenantMemberInfo

Limited info returned by getMember():

interface TenantMemberInfo {
  status: TenantMemberStatus;
  role?: string;
  permMask?: number;
}

Error Handling

All methods return Result<T> from ts-micro-result.

import { tenantAccessErrors } from '@auth-craft/tenant-access-control';

const result = await sdk.getMember({ ... });

if (result.isError()) {
  const error = result.errors[0];

  switch (error?.code) {
    case 'TENANT_MEMBER_NOT_FOUND':
      // Handle not found
      break;
    case 'TENANT_MEMBER_ALREADY_EXISTS':
      // Handle duplicate
      break;
    case 'TENANT_ACCESS_DATABASE_ERROR':
      // Handle database error
      break;
  }
}

Repository Interfaces

For custom implementations:

interface TenantMemberRepository {
  get(tenantId, userId): Promise<Result<TenantMember>>;
  create(data): Promise<Result<void>>;
  updatePermissions(tenantId, userId, updates): Promise<Result<void>>;
  updateStatus(tenantId, userId, status): Promise<Result<void>>;
  remove(tenantId, userId): Promise<Result<void>>;
}

interface SessionRepository {
  findActiveByUserId(userId, options?): Promise<PaginatedResult<SessionInfo>>;
  revokeBatch(sessionIds): Promise<Result<number>>;
}

License

MIT