리소스 - Nora

메모리와 지식은 콘텐츠를 다루는 API입니다. 읽고 쓰려면 PAT content 스코프가 필요하고, 스코프드 리소스에는 서버가 특정 사용자·조직·역할 기준으로 접근 규칙을 평가할 수 있도록 onBehalfOf 주체가 필요합니다.

`onBehalfOf`가 왜 필요한가

PAT은 서비스 토큰이라 최종 사용자가 붙어 있지 않습니다. 스코프드 메모리 스페이스와 지식 폴더는 주체(user_id, org_id, role, …)를 축으로 하는 접근 규칙이 걸려 있습니다. 주체가 없으면 서버가 규칙을 평가할 근거가 없어서, 조용히 전부를 돌려주는 대신 요청을 거절합니다. 스코프드 리소스에는 모든 읽기·쓰기에 onBehalfOf를 넘기세요. 스코프 없는 스페이스·폴더는 없이도 동작하지만, 감사 트레일이 얇아집니다(PAT 소유자만 남고, 실제 최종 사용자가 안 남음).

`memory`

`memory.read`

await nora.memory.read("space_1", {
  onBehalfOf: { user_id: "u_1", role: "member" },
  scope: { topic: "billing" },      // 선택 추가 필터
});

옵션:

onBehalfOf 앱이 주장하는 주체. 스코프드 스페이스에 필수. 거절된 요청은 NoraAccessError를 던집니다.
scope 선택 추가 필터 ({ key: value } 맵이 스페이스의 스코프 스키마와 매칭).

주체가 볼 수 있는 항목을 주어진 스코프 안에서 돌려줍니다. UI의 메모리 뷰어와 같은 모양입니다.

`memory.write`

await nora.memory.write(
  "space_1",
  { path: "notes/billing", body: "…" },
  { onBehalfOf: { user_id: "u_1" } },
);

쓰기는 UI와 같은 큐레이터 · paradigm · supersede 경로를 탑니다. Wiki 노트는 wiki paradigm, Index 노드는 index paradigm, superseded 항목은 표시만 됩니다(삭제가 아닙니다). 쓰기 페이로드의 모양은 스페이스의 paradigm에 따라 다릅니다. paradigm 레퍼런스는 메모리를 참고하세요.

`knowledge`

`knowledge.upload`

await nora.knowledge.upload(fileBlob, {
  folder: "policies",
  onBehalfOf: { org_id: "acme" },
});

옵션:

folder 문서가 들어갈 지식 폴더 태그. 필수.
onBehalfOf 폴더의 접근 규칙에 쓸 주체. 접근 규칙 걸린 폴더에 필수.

CLI의 nora documents upload와 같은 서버 경로입니다. 파일이 청킹·벡터화되고, PAT 소유자와 onBehalfOf 주체 둘 다 감사에 남습니다.

`knowledge.list`

await nora.knowledge.list();

호출자(PAT + 주면 onBehalfOf)가 볼 수 있는 문서를 나열합니다. SDK에는 아직 페이지네이션이 없습니다. 큰 라이브러리엔 --limit / --offset을 지원하는 nora documents list를 쓰세요.

흔한 패턴

인증 레이어에서 요청마다 주체를 넘기기

앱이 이미 아는 호출자 정보를 넘기세요.

async function readNotes(userId: string, topic: string) {
  const user = await yourAuth.get(userId);
  return nora.memory.read("space_notes", {
    onBehalfOf: { user_id: userId, role: user.role, org_id: user.orgId },
    scope: { topic },
  });
}

서버는 넘겨받은 주체를 기준으로 스페이스의 접근 규칙을 평가합니다. 호출자의 role이 스페이스를 볼 수 없으면 NoraAccessError입니다. 던지지 말고 잡아서 다운그레이드할 수 있습니다.

try {
  return await readNotes(userId, topic);
} catch (e) {
  if (e instanceof NoraAccessError) return { entries: [], reason: "access-denied" };
  throw e;
}

공유 주체로 대량 업로드

오퍼레이터 하나가 시작한 배치 인제스트라면, 주체는 오퍼레이터입니다. 문서가 대상으로 하는 최종 사용자가 아닙니다.

for (const file of files) {
  await nora.knowledge.upload(file, {
    folder: "policies",
    onBehalfOf: { user_id: operatorId, role: "admin" },
  });
}

규모가 있으면 nora documents upload-folder를 권합니다. 같은 서버 경로에 재시도·진행 표시를 얹어 배치합니다.

스코프 없는 스페이스·폴더

접근 규칙이 없는 스페이스·폴더에는 onBehalfOf가 선택입니다. 하지만 그래도 넘기면 감사 트레일이 좋아집니다(항목에 오퍼레이터가 누구를 대신했는지 함께 남습니다).

스코프

memory.read / memory.write PAT content.
knowledge.upload / knowledge.list PAT content.
onBehalfOf 없는 스코프드 리소스 거절입니다 (NoraAccessError).

​onBehalfOf가 왜 필요한가

​memory

​memory.read

​memory.write

​knowledge

​knowledge.upload

​knowledge.list

​흔한 패턴

​인증 레이어에서 요청마다 주체를 넘기기

​공유 주체로 대량 업로드

​스코프 없는 스페이스·폴더

​스코프