securing-collections skill
Doctrine extension을 통한 전역 쿼리 필터링과 중첩 리소스 소유권 검증을 위한 link handler를 사용하여 API Platform 컬렉션을 보호합니다.
- GitHub 스타
- 29
- 파일
- 1
- 마지막 커밋
- 2026년 10월 22일
- 라이선스
- —
- 허용된 도구
- —
securing-collections skill은 무엇을 하나요?
Doctrine extension을 통한 전역 쿼리 필터링과 중첩 리소스 소유권 검증을 위한 link handler를 사용하여 API Platform 컬렉션을 보호합니다.
skill의 SKILL.md에서 생성된 요약입니다.
securing-collections skill 정보
이 SKILL은 API Platform 내에서 멀티 테넌트 격리 및 데이터 프라이버시를 구현할 수 있게 합니다. 개발자는 쿼리 수준에서 데이터 액세스를 제한하여 사용자가 자신의 조직이나 계정에 속한 레코드만 볼 수 있도록 보장할 수 있습니다. 이는 전역 쿼리 필터를 위한 Doctrine extension과 중첩된 리소스 URI의 소유권을 검증하는 link handler라는 두 가지 주요 메커니즘을 통해 이루어집니다.
프로젝트에서 soft-delete 필터링, 사용자별 쿼리 범위 제한, 또는 계정 및 메일함과 같은 계층적 경로 보안이 필요한 경우 에이전트가 이 SKILL을 로드해야 합니다. Symfony 사용자의 경우, 이 SKILL은 extension에 autowiring을 활용하여 Doctrine ORM과 MongoDB ODM 모두에 대한 구현을 제공합니다. Laravel 환경의 경우, Eloquent QueryExtensionInterface 사용법과 Eloquent 모델에 필요한 특정 Options 설정에 대한 가이드를 제공합니다. 이 SKILL은 데이터를 가져오기 전에 기반이 되는 QueryBuilder 또는 aggregation pipeline을 수정하여 권한이 없는 데이터 노출을 방지하는 구조화된 코드 패턴을 생성합니다.
agent가 수행할 수 있는 작업
- 1멀티 테넌트 데이터 격리 강제특정 리소스에 대한 모든 쿼리가 사용자의 현재 조직으로 자동 제한되도록 전역 필터를 적용합니다.
- 2soft-delete 기능 구현삭제된 것으로 표시된 레코드를 모든 컬렉션 및 아이템 쿼리에서 자동으로 숨깁니다.
- 3중첩 리소스 URI 보안중첩된 API 경로에 접근할 때 자식 리소스가 올바른 부모 리소스에 속해 있는지 검증합니다.
- 4Laravel Eloquent 필터 구성특정 QueryExtensionInterface 및 서비스 태그 요구 사항을 사용하여 Laravel 프로젝트를 위한 전역 쿼리 extension을 설정합니다.
skill의 SKILL.md를 기반으로 작성되었습니다. 모든 사용 사례는 해당 문서의 인용구와 대조 확인되었습니다.
securing-collections skill 설치 방법
각 명령은 skill 폴더를 클라이언트의 skills 디렉터리에 복사합니다. 클라이언트를 재시작하거나 새 세션을 시작하여 로드하세요.플러그인에 securing-collections skill 설치
/plugin marketplace add api-platform/skillset /plugin install api-platform@api-platform-skillset
Claude Code에 securing-collections skill 설치
~/.claude/skills/securing-collections/SKILL.md
$ npx degit api-platform/skillset/skills/securing-collections ~/.claude/skills/securing-collectionsClaude Code (project)에 securing-collections skill 설치
.claude/skills/securing-collections/SKILL.md
$ npx degit api-platform/skillset/skills/securing-collections .claude/skills/securing-collectionsCodex에 securing-collections skill 설치
~/.agents/skills/securing-collections/SKILL.md
$ npx degit api-platform/skillset/skills/securing-collections ~/.agents/skills/securing-collectionsGemini CLI에 securing-collections skill 설치
~/.gemini/skills/securing-collections/SKILL.md
$ npx degit api-platform/skillset/skills/securing-collections ~/.gemini/skills/securing-collectionsClaude.ai에 securing-collections skill 설치
npx degit api-platform/skillset/skills/securing-collections securing-collections && zip -r securing-collections.zip securing-collections # claude.ai → Customize → Skills → + → Create skill → Upload a skill → securing-collections.zip
자동 검사
2026년 11월 16일에 실행됨전체 보고서 →아직 검증되지 않았습니다. 스킬은 점수 80, 심각한 발견 없음, 검사에 충분한 데이터가 필요합니다. 검사 방식 · 점수를 높이기 위해 수정할 항목
- 소스 저장소 연결 및 접근 가능api-platform/skillset/skills/securing-collections is public and reachablegithub.com/api-platform/skillset/tree/HEAD/skills/securing-c ↗통과
- 오픈 소스 라이선스 (OSI)No license결함 발견
- 최근 1년 내 커밋 또는 릴리스Last commit 2026-10-22github.com/api-platform/skillset/commits ↗통과
- 스크립트에 다운로드 후 실행이나 자격 증명 탈취가 없음No scripts in the skill folder통과
- SKILL.md에 숨겨진 지침 없음No override phrases, safeguard switches, credential requests or hidden charactersgithub.com/api-platform/skillset/blob/HEAD/skills/securing-c ↗통과
- 사전 허용 도구가 제한됨No pre-approved tools; the agent asks before using onegithub.com/api-platform/skillset/blob/HEAD/skills/securing-c ↗통과
- SKILL.md가 Agent Skills 형식을 따름Valid name and description; says when to use it; 238 linesgithub.com/api-platform/skillset/blob/HEAD/skills/securing-c ↗통과
SKILL.md
GitHub에서 보기Securing Collections
Two mechanisms restrict what data users can access at the query level.
Doctrine Extensions (Global Query Filters)
Extensions automatically modify every query for a resource class. Use them for:
- Multi-tenant isolation (filter by organization/user)
- Hiding soft-deleted records
- Any filter that must apply to ALL queries (item + collection)
ORM Extension
<?php
namespace App\Extension;
use ApiPlatform\Doctrine\Orm\Extension\QueryCollectionExtensionInterface;
use ApiPlatform\Doctrine\Orm\Extension\QueryItemExtensionInterface;
use ApiPlatform\Doctrine\Orm\Util\QueryNameGeneratorInterface;
use ApiPlatform\Metadata\Operation;
use Doctrine\ORM\QueryBuilder;
final class AccountExtension implements QueryCollectionExtensionInterface, QueryItemExtensionInterface
{
public function __construct(private UserHelper $userHelper) {}
public function applyToCollection(QueryBuilder $qb, QueryNameGeneratorInterface $queryNameGenerator, string $resourceClass, ?Operation $operation = null, array $context = []): void
{
$this->addWhere($qb, $resourceClass);
}
public function applyToItem(QueryBuilder $qb, QueryNameGeneratorInterface $queryNameGenerator, string $resourceClass, array $identifiers, ?Operation $operation = null, array $context = []): void
{
$this->addWhere($qb, $resourceClass);
}
private function addWhere(QueryBuilder $qb, string $resourceClass): void
{
if (Account::class !== $resourceClass) {
return;
}
$user = $this->userHelper->getUser();
if (!$user) {
return;
}
$rootAlias = $qb->getRootAliases()[0];
$qb->andWhere(sprintf('%s.organization = :org', $rootAlias))
->andWhere(sprintf('%s.isDeleted = :deleted', $rootAlias))
->setParameter('org', $user->getCurrentOrganization())
->setParameter('deleted', false);
}
}
Extensions are auto-registered by Symfony's autowiring. No service tag needed.
MongoDB ODM Extension
Same structure as the ORM version; only the interfaces, the apply-method
signatures, and the query API differ. Implement
AggregationCollectionExtensionInterface / AggregationItemExtensionInterface
(from ApiPlatform\Doctrine\Odm\Extension), and build the filter on a
Doctrine\ODM\MongoDB\Aggregation\Builder instead of a QueryBuilder:
public function applyToCollection(Builder $aggregationBuilder, string $resourceClass, ?Operation $operation = null, array &$context = []): void
{
$this->applyFilters($aggregationBuilder, $resourceClass);
}
// applyToItem adds `array $identifiers` after $resourceClass; both delegate here:
private function applyFilters(Builder $aggregationBuilder, string $resourceClass): void
{
if (Account::class !== $resourceClass) {
return;
}
$user = $this->userHelper->getUser();
if (!$user) {
return;
}
$aggregationBuilder->match()
->field('isDeleted')->equals(false)
->field('organization')->equals($user->getCurrentOrganization()->getId());
}
The ODM apply methods take string $resourceClass directly (no
QueryNameGenerator) and receive $context by reference.
Link Handlers (Nested Resource Security)
Link handlers validate parent resource ownership for nested URIs like /accounts/{accountId}/mailboxes/{mailboxId}/messages.
MongoDB ODM Link Handler
<?php
namespace App\Extension;
use ApiPlatform\Doctrine\Odm\State\LinksHandlerInterface;
use Doctrine\ODM\MongoDB\Aggregation\Builder;
use Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException;
use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
class MessageLinkHandler implements LinksHandlerInterface
{
public function __construct(
private readonly UserHelper $userHelper,
private readonly MailboxRepository $mailboxRepository,
) {}
public function handleLinks(Builder $aggregationBuilder, array $uriVariables, array $context): void
{
$user = $this->userHelper->getUser() ?? throw new AccessDeniedHttpException();
// Validate parent resource exists
$mailbox = $this->mailboxRepository->find($uriVariables['mailboxId'])
?? throw new NotFoundHttpException();
// Validate parent belongs to correct account
if ($mailbox->account->getId() !== ($uriVariables['accountId'] ?? null)) {
throw new NotFoundHttpException();
}
// Validate user has access to this resource tree
if ($mailbox->organization?->getId() !== $user->getCurrentOrganization()?->getId()) {
throw new AccessDeniedHttpException();
}
// Apply query filters
$aggregationBuilder->match()
->field('isDeleted')->equals(false)
->field('mailbox')->equals($mailbox);
// Filter individual item if ID provided
if (isset($uriVariables['id'])) {
$aggregationBuilder->match()
->field('id')->equals($uriVariables['id']);
}
}
}
Assigning to Resource
use ApiPlatform\Doctrine\Odm\State\Options;
#[ApiResource(
operations: [
new Get(
uriTemplate: '/accounts/{accountId}/mailboxes/{mailboxId}/messages/{id}',
uriVariables: ['accountId', 'mailboxId', 'id'],
stateOptions: new Options(
handleLinks: MessageLinkHandler::class,
documentClass: Message::class,
),
),
]
)]
When to Use Which
| Pattern | Use Case |
|---|---|
| Extension | Global filters: multi-tenant isolation, soft-delete, applies to ALL queries for a resource |
| Link Handler | Nested resources: validate parent ownership, scope child queries to parent |
security attribute |
Per-operation checks on already-fetched objects: security: 'object.user == user' |
These mechanisms stack: an extension filters the query, a link handler scopes it to the parent, and security validates the final object.
Laravel (Eloquent)
The two mechanisms exist on Laravel too, but there are no Doctrine extensions.
The global-query-filter equivalent is ApiPlatform\Laravel\Eloquent\Extension\QueryExtensionInterface
— one apply() method covering both item and collection (the Eloquent providers run
it for every query):
<?php
namespace App\Extension;
use ApiPlatform\Laravel\Eloquent\Extension\QueryExtensionInterface;
use ApiPlatform\Metadata\Operation;
use Illuminate\Database\Eloquent\Builder;
final class AccountExtension implements QueryExtensionInterface
{
public function __construct(private readonly UserHelper $userHelper) {}
public function apply(Builder $builder, array $uriVariables, Operation $operation, $context = []): Builder
{
if (Account::class !== $operation->getClass() || !($user = $this->userHelper->getUser())) {
return $builder;
}
return $builder
->where('organization_id', $user->getCurrentOrganization()->id)
->where('is_deleted', false);
}
}
Tag it so the providers pick it up by binding to the QueryExtensionInterface tag in
a service provider ($this->app->tag([AccountExtension::class], QueryExtensionInterface::class));
there is no Symfony autowiring.
For nested-resource ownership, implement
ApiPlatform\Laravel\Eloquent\State\LinksHandlerInterface —
handleLinks(Builder $builder, array $uriVariables, array $context): Builder —
returning the scoped builder (it operates on an Eloquent Builder, not an aggregation
pipeline). Assign it with the Eloquent Options:
use ApiPlatform\Laravel\Eloquent\State\Options;
new Get(
uriTemplate: '/accounts/{accountId}/messages/{id}',
uriVariables: ['accountId', 'id'],
stateOptions: new Options(handleLinks: MessageLinkHandler::class, modelClass: Message::class),
)
Note Eloquent Options uses modelClass: (not documentClass:/entityClass:).
Per-operation security expressions and Laravel policies (viewAny/view/
create/update/delete, or an explicit policy: on an operation) layer on top —
see the operations skill's Laravel section.
이 스킬의 파일
1securing-collections skill 질문
Claude Code에 securing-collections skill을 어떻게 설치하나요?
npx degit api-platform/skillset/skills/securing-collections ~/.claude/skills/securing-collections를 실행합니다. Claude Code는 ~/.claude/skills(모든 프로젝트) 또는 .claude/skills(한 프로젝트)에서 skills를 로드하며, 설명이 작업과 일치할 때 skill을 사용합니다.
securing-collections skill을 사용할 수 있는 클라이언트는 무엇인가요?
Agent Skills 형식을 읽는 모든 클라이언트(Claude Code, Codex, Gemini CLI, claude.ai(ZIP으로 업로드))가 사용할 수 있습니다. skill 내 스크립트는 클라이언트가 코드 실행을 허용하는 경우에만 실행됩니다.
API Platform을 사용하는 Laravel에서 전역 쿼리 필터를 어떻게 구현하나요?
QueryExtensionInterface를 구현하고 서비스 프로바이더에서 태그를 지정해야 합니다. Laravel은 Symfony의 autowiring을 지원하지 않기 때문입니다.
이 메커니즘들을 함께 사용할 수 있나요?
네, 함께 사용할 수 있도록 설계되었습니다. extension이 쿼리를 필터링하고, link handler가 부모 리소스로 범위를 제한하며, 보안 속성이 최종 객체를 검증합니다.