🔐 技術調査 - ReBAC x Clean Architecture

model
  schema 1.1

type user

type document
  relations
    define owner: [user]
    define writer: [user]
    define reader: [user]
    define banned: [user]
    define verified: [user]
    define can_edit: writer and verified
    define can_view: reader but not banned

definition user {}

definition document {
  relation owner: user
  relation writer: user
  relation reader: user
  relation banned: user
  relation verified: user

  permission edit = writer & verified
  permission view = reader - banned
}

model
  schema 1.1

type user

type organization
  relations
    define admin: [user]
    define member: [user]

type folder
  relations
    define parent: [organization]
    define viewer: [user] or member from parent

type document
  relations
    define parent: [folder]
    define viewer: [user] or viewer from parent

src/
├── domain/
│   └── ports/
│       └── authorization.port.ts     # AuthorizationPort インターフェース
├── application/
│   └── use-cases/
│       └── document.use-case.ts      # UseCase（権限チェック挿入済み）
└── adapter/
    ├── inbound/
    │   └── document.controller.ts    # コントローラー
    └── outbound/
        └── authorization/
            ├── openfga.adapter.ts    # OpenFGA アダプター
            └── spicedb.adapter.ts    # SpiceDB アダプター

// domain/ports/authorization.port.ts

export interface CheckRequest {
  user: string;       // 例: "user:alice"
  relation: string;   // 例: "reader"
  object: string;     // 例: "document:123"
  contextualTuples?: TupleKey[];
}

export interface TupleKey {
  user: string;
  relation: string;
  object: string;
}

export interface AuthorizationPort {
  /** 単一の権限チェック */
  check(request: CheckRequest): Promise<boolean>;

  /** ユーザーが指定関係を持つオブジェクト一覧を取得する */
  listObjects(user: string, relation: string, type: string): Promise<string[]>;

  /** 指定オブジェクトに対して指定関係を持つユーザー一覧を取得する */
  listUsers(object: string, objectType: string, relation: string): Promise<string[]>;

  /** タプルを追加する */
  writeTuple(tuple: TupleKey): Promise<void>;

  /** タプルを削除する */
  deleteTuple(tuple: TupleKey): Promise<void>;
}

// adapter/outbound/authorization/openfga.adapter.ts
import { OpenFgaClient } from '@openfga/sdk';
import { AuthorizationPort, CheckRequest, TupleKey } from '../../domain/ports/authorization.port';

export class OpenFgaAdapter implements AuthorizationPort {
  constructor(private readonly client: OpenFgaClient) {}

  async check(request: CheckRequest): Promise<boolean> {
    const { allowed } = await this.client.check({
      user: request.user,
      relation: request.relation,
      object: request.object,
      contextualTuples: request.contextualTuples,
    }, {
      authorizationModelId: process.env.FGA_MODEL_ID,
    });
    return allowed ?? false;
  }

  async listObjects(user: string, relation: string, type: string): Promise<string[]> {
    const response = await this.client.listObjects({
      user,
      relation,
      type,
    }, {
      authorizationModelId: process.env.FGA_MODEL_ID,
    });
    return response.objects ?? [];
  }

  async listUsers(object: string, objectType: string, relation: string): Promise<string[]> {
    const response = await this.client.listUsers({
      object: { type: objectType, id: object },
      relation,
      user_filters: [{ type: 'user' }],
    }, {
      authorizationModelId: process.env.FGA_MODEL_ID,
    });
    return (response.users ?? [])
      .filter(u => u.object) // userset や wildcard を除外する
      .map(u => `${u.object?.type}:${u.object?.id}`);
  }

  async writeTuple(tuple: TupleKey): Promise<void> {
    await this.client.write({
      writes: [{ user: tuple.user, relation: tuple.relation, object: tuple.object }],
    }, {
      authorizationModelId: process.env.FGA_MODEL_ID,
    });
  }

  async deleteTuple(tuple: TupleKey): Promise<void> {
    await this.client.write({
      deletes: [{ user: tuple.user, relation: tuple.relation, object: tuple.object }],
    }, {
      authorizationModelId: process.env.FGA_MODEL_ID,
    });
  }
}

// adapter/outbound/authorization/spicedb.adapter.ts
import { v1 } from '@authzed/authzed-node';
import { AuthorizationPort, TupleKey } from '../../domain/ports/authorization.port';

export class SpiceDbAdapter implements AuthorizationPort {
  private client: ReturnType<typeof v1.NewClient>;
  private promises: ReturnType<typeof v1.NewClient>['promises'];

  constructor(token: string, endpoint: string) {
    this.client = v1.NewClient(token, endpoint);
    this.promises = this.client.promises;
  }

  async check(request: { user: string; relation: string; object: string }): Promise<boolean> {
    const [objectType, objectId] = request.object.split(':');
    const [userType, userId] = request.user.split(':');

    const resource = v1.ObjectReference.create({ objectType, objectId });
    const subject = v1.SubjectReference.create({
      object: v1.ObjectReference.create({ objectType: userType, objectId: userId }),
    });

    const response = await this.promises.checkPermission(
      v1.CheckPermissionRequest.create({
        resource,
        permission: request.relation,
        subject,
      })
    );

    return response.permissionship === v1.CheckPermissionResponse_Permissionship.HAS_PERMISSION;
  }

  async writeTuple(tuple: TupleKey): Promise<void> {
    const [resourceType, resourceId] = tuple.object.split(':');
    const [subjectType, subjectId] = tuple.user.split(':');

    await this.promises.writeRelationships(
      v1.WriteRelationshipsRequest.create({
        updates: [
          v1.RelationshipUpdate.create({
            operation: v1.RelationshipUpdate_Operation.CREATE,
            relationship: v1.Relationship.create({
              resource: v1.ObjectReference.create({ objectType: resourceType, objectId: resourceId }),
              relation: tuple.relation,
              subject: v1.SubjectReference.create({
                object: v1.ObjectReference.create({ objectType: subjectType, objectId: subjectId }),
              }),
            }),
          }),
        ],
      })
    );
  }

  async deleteTuple(tuple: TupleKey): Promise<void> {
    const [resourceType, resourceId] = tuple.object.split(':');
    const [subjectType, subjectId] = tuple.user.split(':');

    await this.promises.writeRelationships(
      v1.WriteRelationshipsRequest.create({
        updates: [
          v1.RelationshipUpdate.create({
            operation: v1.RelationshipUpdate_Operation.DELETE,
            relationship: v1.Relationship.create({
              resource: v1.ObjectReference.create({ objectType: resourceType, objectId: resourceId }),
              relation: tuple.relation,
              subject: v1.SubjectReference.create({
                object: v1.ObjectReference.create({ objectType: subjectType, objectId: subjectId }),
              }),
            }),
          }),
        ],
      })
    );
  }

  async listObjects(user: string, relation: string, type: string): Promise<string[]> {
    // LookupResources API で実装する
    const [subjectType, subjectId] = user.split(':');
    const results: string[] = [];
    const stream = this.client.lookupResources(
      v1.LookupResourcesRequest.create({
        resourceObjectType: type,
        permission: relation,
        subject: v1.SubjectReference.create({
          object: v1.ObjectReference.create({ objectType: subjectType, objectId: subjectId }),
        }),
      })
    );
    for await (const response of stream) {
      results.push(`${type}:${response.resourceObjectId}`);
    }
    return results;
  }

  async listUsers(object: string, objectType: string, relation: string): Promise<string[]> {
    // LookupSubjects API で実装する
    const results: string[] = [];
    const stream = this.client.lookupSubjects(
      v1.LookupSubjectsRequest.create({
        resource: v1.ObjectReference.create({ objectType, objectId: object }),
        permission: relation,
        subjectObjectType: 'user',
      })
    );
    for await (const response of stream) {
      results.push(`user:${response.subjectObjectId}`);
    }
    return results;
  }
}

// application/use-cases/document.use-case.ts

export class GetDocumentUseCase {
  constructor(
    private readonly documentRepository: DocumentRepository,
    private readonly authorizationPort: AuthorizationPort,
  ) {}

  async execute(userId: string, documentId: string): Promise<Document> {
    const allowed = await this.authorizationPort.check({
      user: `user:${userId}`,
      relation: 'reader',
      object: `document:${documentId}`,
    });

    if (!allowed) {
      throw new InsufficientPrivilegeError(`user:${userId} は document:${documentId} を読み取れません`);
    }

    return this.documentRepository.findById(documentId);
  }
}

// application/use-cases/list-documents.use-case.ts

export class ListDocumentsUseCase {
  constructor(
    private readonly documentRepository: DocumentRepository,
    private readonly authorizationPort: AuthorizationPort,
  ) {}

  async execute(userId: string): Promise<Document[]> {
    const accessibleObjectIds = await this.authorizationPort.listObjects(
      `user:${userId}`,
      'reader',
      'document',
    );

    if (accessibleObjectIds.length === 0) {
      return [];
    }

    const documentIds = accessibleObjectIds.map(obj => obj.replace('document:', ''));
    return this.documentRepository.findByIds(documentIds);
  }
}

# OpenFGA を Docker で起動する
docker run -p 8080:8080 -p 8081:8081 -p 3000:3000 \
  openfga/openfga run

# ストアを作成する
fga store create --name "my-app"

# 環境変数を設定する
export FGA_API_URL=http://localhost:8080
export FGA_STORE_ID=<store_id>

# SpiceDB を Docker で起動する（インメモリ、開発用）
docker run -p 50051:50051 authzed/spicedb serve \
  --grpc-preshared-key "my-token" \
  --datastore-engine memory

# zed CLI でスキーマを書き込む
zed schema write schema.zed \
  --endpoint localhost:50051 \
  --token my-token \
  --insecure

model
  schema 1.1

type user

type organization
  relations
    define admin: [user]
    define member: [user]

type document
  relations
    define owner: [user]
    define writer: [user, organization#member]
    define reader: [user, organization#member]
    define can_edit: owner or writer
    define can_view: can_edit or reader

definition user {}

definition organization {
  relation admin: user
  relation member: user
}

definition document {
  relation owner: user
  relation writer: user | organization#member
  relation reader: user | organization#member

  permission edit = owner + writer
  permission view = edit + reader
}

// OpenFGA: ユーザー alice に document:123 の reader 権限を付与する
await fgaClient.write({
  writes: [
    { user: 'user:alice', relation: 'reader', object: 'document:123' },
  ],
}, {
  authorizationModelId: process.env.FGA_MODEL_ID,
});

// SpiceDB: ユーザー alice に document:123 の reader 関係を書き込む
await promiseClient.writeRelationships(
  v1.WriteRelationshipsRequest.create({
    updates: [
      v1.RelationshipUpdate.create({
        operation: v1.RelationshipUpdate_Operation.CREATE,
        relationship: v1.Relationship.create({
          resource: v1.ObjectReference.create({ objectType: 'document', objectId: '123' }),
          relation: 'reader',
          subject: v1.SubjectReference.create({
            object: v1.ObjectReference.create({ objectType: 'user', objectId: 'alice' }),
          }),
        }),
      }),
    ],
  })
);

const { allowed } = await fgaClient.check({
  user: 'user:alice',
  relation: 'can_view',
  object: 'document:123',
}, {
  authorizationModelId: process.env.FGA_MODEL_ID,
});

if (!allowed) throw new ForbiddenError();

const response = await fgaClient.batchCheck({
  checks: [
    { user: 'user:alice', relation: 'reader', object: 'document:123' },
    { user: 'user:alice', relation: 'writer', object: 'document:456' },
  ],
}, {
  authorizationModelId: process.env.FGA_MODEL_ID,
});
// response.result には correlationId をキーとした結果マップが返る

// ListObjects: ユーザーがアクセスできるオブジェクト一覧
const response = await fgaClient.listObjects({
  user: 'user:alice',
  relation: 'reader',
  type: 'document',
}, {
  authorizationModelId: process.env.FGA_MODEL_ID,
});
// response.objects = ["document:123", "document:456"]

// ListUsers: オブジェクトにアクセスできるユーザー一覧
const response = await fgaClient.listUsers({
  object: { type: 'document', id: '123' },
  relation: 'reader',
  user_filters: [{ type: 'user' }],
}, {
  authorizationModelId: process.env.FGA_MODEL_ID,
});

// OpenFGA: JWT のグループクレームをコンテキストタプルとして渡す
const { allowed } = await fgaClient.check({
  user: 'user:alice',
  relation: 'can_view',
  object: 'document:123',
  contextualTuples: [
    {
      user: 'user:alice',
      relation: 'member',
      object: 'organization:acme',
    },
  ],
}, {
  authorizationModelId: process.env.FGA_MODEL_ID,
});

openfga run \
  --metrics-enabled=true \
  --datastore-metrics-enabled=true \
  --trace-enabled=true \
  --trace-sample-ratio=0.3

OPENFGA_STORE_ID=<store_id>
OPENFGA_MODEL_ID=<model_id>

old_result = fga.check(model_id=OLD_MODEL_ID, ...)
new_result = fga.check(model_id=NEW_MODEL_ID, ...)
if old_result != new_result:
    logger.warning("Model behavior divergence detected")

def handle_resource_created(event):
    fga.write(tuples=[
        {"user": f"user:{event.owner_id}",
         "relation": "owner",
         "object": f"document:{event.resource_id}"}
    ])
    mark_event_as_processed(event.id)

def check_with_fallback(user_id, resource_id):
    pending = db.get_pending_outbox_events(resource_id)
    contextual = [to_contextual_tuple(e) for e in pending]

    return fga.check(
        user=f"user:{user_id}",
        relation="reader",
        object=f"document:{resource_id}",
        contextual_tuples=contextual,
    )

OPENFGA_DATASTORE_MIN_OPEN_CONNS=10       # DB 最大接続数の 10〜30%
OPENFGA_DATASTORE_MAX_OPEN_CONNS=50       # サーバー台数で均等割する

OPENFGA_MAX_CONCURRENT_READS_FOR_CHECK=20
OPENFGA_MAX_CONCURRENT_READS_FOR_LIST_OBJECTS=10
OPENFGA_RESOLVE_NODE_LIMIT=25       # 再帰深さ制限
OPENFGA_RESOLVE_NODE_BREADTH_LIMIT=25   # 横幅制限（デフォルト: 25）

# 非推奨: 個別 Check を繰り返す
for doc_id in document_ids:
    result = fga.check(user="user:alice", relation="reader", object=f"document:{doc_id}")

# 推奨: ListObjects で一括取得する
accessible_docs = fga.list_objects(user="user:alice", relation="reader", type="document")

// adapter/inbound/middleware/auth.middleware.ts
export function requireRole(role: string) {
  return (req: Request, res: Response, next: NextFunction) => {
    const token = req.headers.authorization?.split(' ')[1];
    const payload = verifyJwt(token);
    if (!payload.roles.includes(role)) {
      return res.status(403).json({ error: 'Forbidden' });
    }
    req.user = payload;
    next();
  };
}

// エンドポイント単位の粗い認可
router.use('/admin', requireRole('admin'));

// application/use-cases/edit-document.use-case.ts
export class EditDocumentUseCase {
  constructor(
    private readonly authorizationPort: AuthorizationPort,
    private readonly documentPolicyService: DocumentPolicyService,
    private readonly documentRepository: DocumentRepository,
  ) {}

  async execute(userId: string, documentId: string, content: string): Promise<void> {
    // 1. ReBAC による関係チェック（UseCase レイヤー）
    const allowed = await this.authorizationPort.check({
      user: `user:${userId}`,
      relation: 'writer',
      object: `document:${documentId}`,
    });
    if (!allowed) throw new InsufficientPrivilegeError();

    const document = await this.documentRepository.findById(documentId);

    // 2. ドメイン不変条件チェック（Domain Service）
    if (!this.documentPolicyService.canBeEdited(document)) {
      throw new DomainRuleViolationError('承認済みドキュメントは編集できません');
    }

    document.updateContent(content);
    await this.documentRepository.save(document);
  }
}

// domain/services/document-policy.service.ts
export class DocumentPolicyService {
  canBeEdited(document: Document): boolean {
    if (document.status === DocumentStatus.APPROVED) {
      return false;
    }
    return true;
  }

  canBeShared(document: Document): boolean {
    if (document.status === DocumentStatus.DRAFT) {
      return false;
    }
    return true;
  }
}

// adapter/outbound/repositories/document.repository.ts
export class DocumentRepository {
  constructor(
    private readonly db: Database,
    private readonly authorizationPort: AuthorizationPort,
  ) {}

  async findAccessibleByUser(userId: string): Promise<Document[]> {
    const accessibleIds = await this.authorizationPort.listObjects(
      `user:${userId}`, 'reader', 'document'
    );
    if (accessibleIds.length === 0) return [];
    const ids = accessibleIds.map(obj => obj.replace('document:', ''));
    return this.db.query('SELECT * FROM documents WHERE id = ANY($1)', [ids]);
  }
}

# fga.yaml
name: Document Access Tests
model_file: model.fga
tuples:
  - user: user:alice
    relation: owner
    object: document:budget
tests:
  - name: owner can edit
    check:
      - user: user:alice
        object: document:budget
        assertions:
          edit: true
  - name: non-member cannot edit
    check:
      - user: user:bob
        object: document:budget
        assertions:
          edit: false

fga model test --tests fga.yaml

def test_edit_document_denied():
    mock_authz = Mock(spec=AuthorizationPort)
    mock_authz.can_edit.return_value = False

    use_case = EditDocumentUseCase(authz_port=mock_authz)

    with pytest.raises(InsufficientPrivilegeError):
        use_case.execute(user_id="user:bob", document_id="doc:1", content="...")

openfga run --datastore-engine=memory

# SpiceDB の ZedToken 使用例
response = spicedb.write_relationships(...)
zed_token = response.written_at

# リソースに ZedToken を付与して保存する
db.save(resource, consistency_token=zed_token)

# Check 時に ZedToken を使用する
spicedb.check_permission(
    resource=...,
    consistency={"at_least_as_fresh": zed_token}
)

zed permission check group:parent member group:child --explain

is_ancestor = spicedb.check_permission(
    resource={"type": "group", "id": "child"},
    permission="member",
    subject={"object": {"type": "group", "id": "parent"}}
)
if is_ancestor:
    raise CircularReferenceError("循環参照が発生します")

# dispatch_count の高いクエリを特定する（Prometheus クエリ例）
histogram_quantile(0.99, rate(openfga_dispatch_count_bucket[5m]))